@scayle/eslint-config-storefront 5.1.1 → 5.2.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @aboutyou/eslint-config-sfc
 
+## 5.2.1
+
+### Patch Changes
+
+- Updated dependency `@typescript-eslint/utils@^8.70.0` to `@typescript-eslint/utils@^8.71.0`
+- Updated dependency `eslint-plugin-jsdoc@^64.2.1` to `eslint-plugin-jsdoc@^65.0.0`
+- Updated dependency `typescript-eslint@^8.70.0` to `typescript-eslint@^8.71.0`
+- Updates `eslint-plugin-jsdoc` to v65 and aligns `typescript-eslint`, `@typescript-eslint/utils`, and `@typescript-eslint/rule-tester` on `^8.71.0`. The config doesn't enable the two `eslint-plugin-jsdoc` rules whose behavior changed in v65 (`check-indentation` and `check-line-alignment`), so existing lint setups are unaffected unless they enable those rules themselves. Keeping the `@typescript-eslint` packages on one version avoids duplicate copies of the AST types in a consumer's `node_modules`, which can break type checks on custom rules.
+
+## 5.2.0
+
+### Minor Changes
+
+- Adds a new `require-lazy-promise-in-view-props` rule to the V3 entry point (`storefrontV3()`), enabled at `error`. It flags a promise created inside a controller's `getViewProps()` that isn't wrapped in `lazyPromise` and isn't awaited or returned immediately, catching both wasted fetches on partial reloads and unhandled promise rejections.
+
+  This rule needs real type information to work, and it reads that from the same `resolver.tsconfigPath` option consumers already set for the import resolver. Because ESLint flat config merges type information across every config block matching a file, every consumer that sets `resolver.tsconfigPath` now gets real type-aware linting from `eslint-plugin-sonarjs` across their whole TypeScript codebase, not just from this new rule. `eslint-plugin-sonarjs`'s type-aware rules (`sonarjs/deprecation`, `sonarjs/different-types-comparison`, `sonarjs/no-redundant-optional`, and others) previously ran without type information and silently found nothing; they now report real findings. Existing consumers should expect to see and fix new `sonarjs` errors the first time they lint after upgrading.
+
+### Patch Changes
+
+- Added dependency `@typescript-eslint/utils@^8.70.0`
+- Added dependency `ts-api-utils@^2.1.2`
+- Updated dependency `eslint-plugin-unicorn@^74.0.0` to `eslint-plugin-unicorn@^76.0.0`
+- Updated dependency `typescript-eslint@^8.67.0` to `typescript-eslint@^8.70.0`
+- Speed up the V3 flat config. `@intlify/vue-i18n/no-unused-keys` now excludes test and story files from its scan, since they don't introduce translation key usages beyond what source files already have. `sonarjs/aws-restricted-ip-admin-access` and `better-tailwindcss/no-deprecated-classes` are turned off: the former only fires on AWS CDK code, the latter only on Tailwind v3 class names, and the `/v3` entry point is Tailwind v4 only.
+
 ## 5.1.1
 
 ### Patch Changes

package/README.md

@@ -11,6 +11,28 @@ Should you require support for `eslint@8`, please use `@scayle/eslint-config-sto
 
 ---
 
+## Entry points
+
+The package exposes three entry points, all built on the same shared rule set. Pick the one
+that matches your stack:
+
+| Entry point | Export                                  | For                                                                                               | Adds on top of the shared rules                                                                                                                                                                                                                                                                         |
+| ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Default     | `@scayle/eslint-config-storefront`      | Framework-agnostic TypeScript/Node.js packages                                                    | JavaScript, TypeScript, JSDoc, and import rules                                                                                                                                                                                                                                                         |
+| Nuxt        | `@scayle/eslint-config-storefront/nuxt` | Nuxt projects — this is what **Storefront Application V2** uses, since V2 is a Nuxt 4 application | Nothing beyond the shared rules; `@nuxt/eslint` already supplies JavaScript, TypeScript, JSDoc, and import rules                                                                                                                                                                                        |
+| V3          | `@scayle/eslint-config-storefront/v3`   | The **Storefront Application V3** stack (Hono + Inertia.js + Vue 3, _not_ Nuxt)                   | Everything the default entry point adds, plus Vue language wiring, Vue rules, accessibility rules, `vue-i18n` linting, `@scayle/vue-composable` rules, Storybook file conventions, Tailwind CSS class validation, a TypeScript-aware import resolver, and the `require-lazy-promise-in-view-props` rule |
+
+There is no `/v2` entry point: Storefront Application V2 is a Nuxt application, so it uses the
+`/nuxt` entry point directly, the same as any other Nuxt project. "V2" and "V3" describe the two
+Storefront Application stacks this monorepo ships, not two separate ESLint configs — V2 maps to
+`/nuxt`, V3 maps to `/v3`.
+
+Internally, `/nuxt` and `/v3` both build on the same base config, so a rule fixed or added to the
+shared set (JavaScript, Node.js, JSON/JSONC, test files, SonarJS, Promise usage, modernization,
+regex safety, comments hygiene) applies to every entry point without duplicating configuration.
+Only `/v3` and the default entry point add TypeScript, JSDoc, and import rules directly — `/nuxt`
+relies on `@nuxt/eslint` for those instead.
+
 ## Install
 
 Add the `@scayle/eslint-config-storefront` manually to your project:
@@ -28,7 +50,7 @@ import storefront from '@scayle/eslint-config-storefront'
 export default storefront()
 ```
 
-### Nuxt projects
+### Nuxt projects (Storefront Application V2)
 
 Nuxt projects already get JavaScript, TypeScript, JSDoc, and import rules from
 [`@nuxt/eslint`](https://eslint.nuxt.com/). Use the `/nuxt` entry point instead, which
@@ -43,12 +65,15 @@ import withNuxt from './.nuxt/eslint.config.mjs'
 export default withNuxt(storefrontNuxt())
 ```
 
+This is the entry point Storefront Application V2's own `eslint.config.mjs` uses.
+
 ### Storefront Application V3 projects
 
 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, Tailwind CSS class validation, and a TypeScript-aware import resolver:
+conventions, Tailwind CSS class validation, a TypeScript-aware import resolver, and the
+`require-lazy-promise-in-view-props` rule:
 
 ```js
 // eslint.config.mjs
@@ -70,14 +95,76 @@ 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
+- `resolver.tsconfigPath`: absolute path to a `tsconfig.json` for the import resolver and,
+  with the same `?? typescript.tsconfigPath` fallback, for type-checking the
+  `require-lazy-promise-in-view-props` rule below — independent of `typescript.tsconfigPath`
+  in the sense that setting it does not switch on `@typescript-eslint/*` type-checked rules
+  (`recommendedTypeChecked`) generally. Use this instead of `typescript.tsconfigPath` when you
+  want the resolver fix and the lazy-promise rule without also switching on
+  `@typescript-eslint/*` type-checked rules project-wide. When neither option resolves a
+  tsconfig path, `require-lazy-promise-in-view-props` is omitted entirely rather than
+  registered without type information. Setting it DOES have one other real effect: because
+  ESLint flat config merges type information across every config block matching a file, and
+  the lazy-promise rule's own block matches every `.ts`/`.tsx`/`.mts`/`.cts` file (not just
+  files with a `getViewProps` method), `eslint-plugin-sonarjs`'s type-aware rules gain real
+  type information project-wide too — they silently report nothing without a type checker, so
+  expect new `sonarjs` findings the first time you set this option, not just wherever the
+  lazy-promise rule itself looks
 - `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)
 
+This is the entry point Storefront Application V3's own `eslint.config.mjs` uses.
+
+#### Vue rules and accessibility
+
+`/v3` wires the Vue parser (including `<script setup lang="ts">`) via `vue-eslint-parser`, applies
+`eslint-plugin-vue`'s essential, strongly-recommended, and recommended presets, and layers a
+handful of Storefront-specific overrides on top (e.g. `vue/custom-event-name-casing`,
+`vue/block-order`, styling rules disabled where they conflict with this project's Prettier
+config). `vue-eslint-parser` doesn't reuse the type-aware `@typescript-eslint/no-unused-vars`
+config from the TypeScript rules, since that one only scopes to `.ts`/`.tsx`/`.mts`/`.cts` files,
+so `.vue` files get their own registration of the same rule.
+
+Vue accessibility rules (`eslint-plugin-vuejs-accessibility`'s recommended preset) are wired but
+every rule ships `off` by default. That baseline reflects that a11y coverage is opt-in until a
+consuming project runs its own audit and turns rules on deliberately — it is not a statement that
+accessibility doesn't matter.
+
+#### `vue-i18n` linting
+
+Validates message syntax, catches missing/unused/duplicate translation keys, and — only in
+CI (`process.env.CI` set) — enforces that every locale file carries the same keys as the others
+at `error` (a local `warn` lets you author a key in one locale before running the translation
+step). Requires `i18n.localeDir` to be set; there is no default, since the plugin can't validate
+anything without a real path to your locale files.
+
+#### `@scayle/vue-composable` rules
+
+Enables all five rules from the sibling
+[`@scayle/eslint-plugin-vue-composable`](../eslint-plugin-vue-composable) package at `error`:
+`no-composable-after-await`, `no-lifecycle-after-await`, `no-watch-after-await`,
+`no-computed-after-await` (composables/lifecycle hooks/watchers/computed refs called after an
+`await` inside a composable bind to the wrong instance), and
+`require-explicit-fallthrough-attrs` (multi-root components must declare `inheritAttrs: false`,
+since Vue can't infer where fallthrough attributes should land). See that package's own README
+for the full rationale and examples per rule.
+
+#### Storybook conventions
+
+Applies `eslint-plugin-storybook`'s recommended preset to files matching `*.stories.*` /
+`*.story.*`. No configuration needed.
+
+#### Tailwind CSS class validation
+
+Validates Tailwind utility classes via `eslint-plugin-better-tailwindcss`'s recommended preset,
+against the CSS entry point you provide in `tailwind.entryPoint`. Class-order and
+line-wrapping rules are disabled, since this project's Prettier Tailwind plugin already handles
+sorting and would otherwise conflict with the ESLint plugin's own ordering opinion.
+`no-deprecated-classes` is disabled too: the `/v3` entry point targets Tailwind v4, so this
+rule's v3 class-name findings don't apply.
+
 #### Import resolution
 
 `/v3` wires `eslint-import-resolver-typescript`, so `import-x` rules resolve `tsconfig.json`
@@ -103,6 +190,64 @@ 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.
 
+#### `require-lazy-promise-in-view-props`
+
+Enforces the `lazyPromise` convention in Inertia controllers: a promise created inside a
+controller's `getViewProps()` method must be wrapped in the SDK's `lazyPromise(() => ...)`
+helper, unless it's awaited or returned in the same statement it's created in. This closes
+two related problems that a promise created eagerly in `getViewProps()` can cause: a
+partial reload that excludes every prop consuming that promise still triggers the fetch
+(wasted work), and an uncaught rejection on such a promise can surface as an unhandled
+promise rejection. The rule reports at `error` and offers a suggestion (not an autofix,
+since call sites also need to change from a bare reference to an accessor call, `x` → `x()`)
+that wraps the flagged expression.
+
+```ts
+// Before — flagged
+const productsPromise = fetchProducts(params)
+return {
+  products: async () => (await productsPromise).items,
+  pagination: async () => (await productsPromise).pagination,
+}
+
+// After — the suggested fix, plus updating both call sites
+const getProducts = lazyPromise(() => fetchProducts(params))
+return {
+  products: async () => (await getProducts()).items,
+  pagination: async () => (await getProducts()).pagination,
+}
+```
+
+The rule is type-aware: it detects any thenable-typed local (not just a literal `Promise`
+name match), so a `PromiseLike`-shaped or branded return type is caught too. It only checks
+locals declared directly in `getViewProps()`'s own body — a promise created and consumed
+entirely inside a nested function (a prop callback, a nested class's method) is not flagged,
+since that promise is already effectively lazy: the enclosing function only runs when it's
+invoked. A correctly-wrapped `lazyPromise(() => ...)` call itself returns a function, not a
+thenable, so it never trips the check; passing `lazyPromise` an already-invoked promise
+instead of a factory (`lazyPromise(fetchThing())` instead of
+`lazyPromise(() => fetchThing())`) is a type error the TypeScript compiler catches on its
+own — the wrong argument shape doesn't satisfy `lazyPromise`'s signature — so the rule
+doesn't need its own check for that case.
+
+Known limitations: the rule does not verify that the `lazyPromise` identifier it sees
+resolves to the SDK's own export — a same-named local declaration would also satisfy it. It
+likewise doesn't verify that a consuming prop callback actually chains the accessor's result
+into its own return value; a callback that calls the accessor without awaiting or returning
+it could still produce an unhandled rejection the rule won't catch. It also doesn't track
+references across sibling declarators in the same body, so two independent promises
+consumed together via `Promise.all([a, b])` are each flagged individually even though
+neither needs `lazyPromise` there.
+
+Requires `resolver.tsconfigPath` or `typescript.tsconfigPath` to be set — see
+[Import resolution](#import-resolution) above. When neither is set, the rule is omitted
+entirely from the config rather than registered without type information, which would
+otherwise crash ESLint on the first `.ts` file it lints. Note that `resolver.tsconfigPath`
+is passed to `parserOptions.projectService.defaultProject`, which is a fallback for files
+not covered by an auto-discovered `tsconfig.json` — and which typescript-eslint hard-fails
+on after 8 unmatched files by design. If your project's own `tsconfig.json` doesn't cover
+every `.ts` file this rule lints, you may see an ESLint crash rather than a lint error.
+
 ### Add script for package.json
 
 For example:
@@ -149,6 +294,69 @@ Add the following settings to your `.vscode/settings.json`:
 }
 ```
 
+## What the shared rules cover
+
+Every entry point (default, `/nuxt`, `/v3`) includes the following rule domains. They live in
+`config/rules.mjs`, `config/javascript.mjs`, `config/typescript.mjs`, `config/unicorn.mjs`,
+`config/test.mjs`, and `config/ignores.mjs` in this package's source, one factory function per
+domain:
+
+- **Comments hygiene** (`eslint-comments/*`): no aggregating/duplicate/unlimited
+  `eslint-disable` comments, no unused `eslint-enable`.
+- **Node.js** (`node/*`): deprecated API usage, callback error-handling conventions,
+  `process`/`Buffer` globals preferred over the bare identifiers.
+- **JSON/JSONC** (`jsonc/*`): structural validity plus formatting rules for `.json`,
+  `.json5`, and `.jsonc` files.
+- **Test files** (`vitest/*`, `no-only-tests/*`): `it`/`describe` conventions, no
+  duplicate test titles, no accidental `.only` left in committed code (`error` in CI,
+  `warn` locally so you can use `.only` while debugging).
+- **SonarJS** (`sonarjs/*`): the plugin's recommended preset, with `no-duplicate-string`
+  off, `todo-tag`/`fixme-tag` downgraded to `warn`, and `aws-restricted-ip-admin-access`
+  off (it only fires on AWS CDK infrastructure code).
+- **Promise usage** (`promise/*`): a curated subset of `eslint-plugin-promise`'s rules —
+  `no-multiple-resolved`, `no-new-statics`, and `no-return-wrap` at `error`, the rest at
+  `warn`. `catch-or-return` and `always-return` only inspect a promise used as a bare
+  statement, so a project whose promises are all stored in a variable before being awaited
+  or returned (as V3's controller code is) can safely turn both `off` in its own
+  `eslint.config.mjs` — Storefront Application V3's own config does exactly that.
+  (`require-lazy-promise-in-view-props` is what enforces the equivalent convention for V3
+  controllers; see above.)
+- **Modernization** (`unicorn/*`, `e18e/*`): a curated subset of `eslint-plugin-unicorn`
+  (not its full `recommended` preset, which is hundreds of largely stylistic rules), plus
+  the [e18e](https://e18e.dev) community's rule set for modernization, module-replacement,
+  and performance findings. Every `e18e/*` rule ships at `warn` — the plugin is still
+  pre-1.0 and its rule set hasn't been reviewed against every consuming project yet, so a
+  warning surfaces a finding without failing your build. See
+  [`e18e/*` rules ship as warnings](#e18e-rules-ship-as-warnings) below for the one rule
+  worth knowing about specifically.
+- **Regex safety** (`regexp/*`): `eslint-plugin-regexp`'s recommended preset, including
+  ReDoS-prone pattern detection.
+
+The default and `/v3` entry points additionally include:
+
+- **JavaScript** (`@eslint/js`'s recommended preset plus Storefront-specific additions):
+  strict equality, no implicit globals, consistent `const`/`let` usage, and similar
+  correctness rules that apply regardless of TypeScript.
+- **TypeScript** (`@typescript-eslint/*`): the plugin's recommended preset, upgraded to
+  `recommendedTypeChecked` when a `tsconfigPath` is provided (see
+  [Storefront Application V3 projects](#storefront-application-v3-projects) above for how
+  V3 supplies one), plus Storefront-specific overrides — consistent type-only imports,
+  `interface` over `type` for object shapes, unused-variable detection that allows a
+  leading underscore to mark an intentionally-unused binding.
+- **JSDoc** (`jsdoc/*`): validates JSDoc comment structure (parameter names, return
+  descriptions, alignment) at `warn`. This package is published and consumed by external
+  developers, so exported symbols are expected to carry meaningful documentation.
+- **Import correctness** (`import-x/*`): duplicate imports, mutable exports, self-imports,
+  extraneous dependencies not declared in `package.json`, and consistent type-import
+  specifier style.
+- **Ignore patterns**: build artifacts, lockfiles, and tooling caches (`node_modules`,
+  `dist`, `.output`, coverage reports, and similar) are excluded, on top of whatever your
+  project's own `.gitignore` excludes.
+
+`/nuxt` omits all five of the above: `@nuxt/eslint` already provides JavaScript, TypeScript,
+JSDoc, and import rules for a Nuxt project, and Nuxt's own tooling manages its build-output
+ignore patterns.
+
 ## Customization
 
 ### Default config / `@scayle/eslint-config-storefront`

package/config/rules.mjs

@@ -89,6 +89,8 @@ const SONARJS_RULES = {
   'sonarjs/no-duplicate-string': 'off',
   'sonarjs/todo-tag': 'warn',
   'sonarjs/fixme-tag': 'warn',
+  // Flags AWS CDK infrastructure code, which none of our projects use.
+  'sonarjs/aws-restricted-ip-admin-access': 'off',
 }
 
 /** @returns {import('eslint').Linter.Config[]} Flat config entries for SonarJS rules. */

package/config/v3/__fixtures__/require-lazy-promise/file.ts

@@ -0,0 +1 @@
+export {}

package/config/v3/__fixtures__/require-lazy-promise/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["file.ts"]
+}

package/config/v3/requireLazyPromise.mjs

@@ -0,0 +1,127 @@
+import { ESLintUtils } from '@typescript-eslint/utils'
+import * as tsutils from 'ts-api-utils'
+
+const createRule = ESLintUtils.RuleCreator(
+  () =>
+    'https://github.com/scayle/eslint-config-storefront/blob/main/config/v3/requireLazyPromise.mjs',
+)
+
+const rule = createRule({
+  name: 'require-lazy-promise-in-view-props',
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require promises created in getViewProps() to be wrapped in lazyPromise unless awaited or returned immediately.',
+    },
+    schema: [],
+    hasSuggestions: true,
+    messages: {
+      requireLazyPromise:
+        'Wrap this promise in `lazyPromise(() => ...)` so it only runs when a prop actually consumes it. A partial reload that excludes every consuming prop otherwise still triggers this fetch, and an uncaught rejection here can become an unhandled promise rejection.',
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    const services = ESLintUtils.getParserServices(context)
+    const checker = services.program.getTypeChecker()
+
+    return {
+      VariableDeclarator(node) {
+        const init = node.init
+        if (init == null) {
+          return
+        }
+
+        // Only flag declarators directly inside getViewProps's own body. A
+        // promise inside a nested function (a prop callback, a nested method)
+        // is already lazy by construction, since that function only runs
+        // when invoked — reporting there would be a false positive.
+        const owner = context.sourceCode.getScope(node).variableScope.block
+        if (
+          owner.type !== 'FunctionExpression' ||
+          owner.parent.type !== 'MethodDefinition' ||
+          owner.parent.key.type !== 'Identifier' ||
+          owner.parent.key.name !== 'getViewProps'
+        ) {
+          return
+        }
+
+        // A correctly-wrapped `lazyPromise(() => ...)` call returns a
+        // function, not a thenable, so the type check below already skips
+        // it — no separate call-shape check needed.
+        const tsNode = services.esTreeNodeToTSNodeMap.get(init)
+        if (
+          !tsutils.isThenableType(
+            checker,
+            tsNode,
+            checker.getTypeAtLocation(tsNode),
+          )
+        ) {
+          return
+        }
+
+        context.report({
+          node: init,
+          messageId: 'requireLazyPromise',
+          suggest: [
+            {
+              messageId: 'requireLazyPromise',
+              fix: (fixer) =>
+                fixer.replaceText(
+                  init,
+                  `lazyPromise(() => ${context.sourceCode.getText(init)})`,
+                ),
+            },
+          ],
+        })
+      },
+    }
+  },
+})
+
+/**
+ * Enables the `require-lazy-promise-in-view-props` rule. This rule requires type
+ * information, so it is a no-op (returns no config entries) when `tsconfigPath`
+ * cannot be resolved — registering the rule without type information would crash
+ * ESLint's entire run on the first `.ts` file, rather than degrading gracefully.
+ * @param {string} [tsconfigPath] Absolute path to the tsconfig.json used as the
+ *   default project for files not covered by an auto-discovered tsconfig.
+ * @returns {import('eslint').Linter.Config[]} Flat config entries for the require-lazy-promise
+ *   rule, or an empty array when no tsconfig path is resolvable.
+ */
+export function requireLazyPromiseConfig(tsconfigPath) {
+  if (!tsconfigPath) {
+    return []
+  }
+
+  return [
+    {
+      name: 'storefront/v3/require-lazy-promise',
+      files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'],
+      languageOptions: {
+        parserOptions: {
+          projectService: { defaultProject: tsconfigPath },
+          tsconfigRootDir: process.cwd(),
+        },
+      },
+      plugins: {
+        storefront: {
+          rules: {
+            // @typescript-eslint/utils RuleModuleWithName is compatible at runtime but
+            // structurally incompatible with ESLint's Rule.RuleModule; bridge via unknown cast
+            'require-lazy-promise-in-view-props':
+              /** @type {import('eslint').Rule.RuleModule} */ (
+                /** @type {unknown} */ (rule)
+              ),
+          },
+        },
+      },
+      rules: {
+        'storefront/require-lazy-promise-in-view-props': 'error',
+      },
+    },
+  ]
+}
+
+export default rule

package/config/v3/requireLazyPromise.test.mjs

@@ -0,0 +1,170 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import { describe, it } from 'vitest'
+import rule from './requireLazyPromise.mjs'
+
+RuleTester.describe = describe
+RuleTester.it = it
+// Required RuleTester wiring, not a left-in test filter: this assigns the reference so a test
+// CASE can opt into `only: true`; it does not itself run any test with `.only`.
+RuleTester.itOnly = it.only // eslint-disable-line no-only-tests/no-only-tests
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const fixtureDir = path.join(__dirname, '__fixtures__', 'require-lazy-promise')
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parserOptions: {
+      project: path.join(fixtureDir, 'tsconfig.json'),
+      tsconfigRootDir: fixtureDir,
+    },
+  },
+})
+
+const filename = 'file.ts'
+
+ruleTester.run('require-lazy-promise-in-view-props', rule, {
+  valid: [
+    {
+      name: 'lazyPromise-wrapped local',
+      filename,
+      code: `
+        declare function lazyPromise<T>(factory: () => Promise<T>): () => Promise<T>
+        declare function fetchThing(): Promise<string>
+        class C {
+          getViewProps() {
+            const getThing = lazyPromise(() => fetchThing())
+            return { thing: async () => await getThing() }
+          }
+        }
+      `,
+    },
+    {
+      name: 'promise awaited inline, never stored',
+      filename,
+      code: `
+        declare function fetchThing(): Promise<string>
+        class C {
+          async getViewProps() {
+            return { thing: await fetchThing() }
+          }
+        }
+      `,
+    },
+    {
+      name: 'non-thenable local is ignored',
+      filename,
+      code: `
+        class C {
+          getViewProps() {
+            const category = { id: 1 }
+            return { category }
+          }
+        }
+      `,
+    },
+    {
+      name: 'method not named getViewProps is ignored',
+      filename,
+      code: `
+        declare function fetchThing(): Promise<string>
+        class C {
+          getOtherProps() {
+            const thingPromise = fetchThing()
+            return { thing: async () => await thingPromise }
+          }
+        }
+      `,
+    },
+    {
+      name: 'promise created and consumed entirely inside a prop callback is not flagged (already lazy by construction)',
+      filename,
+      code: `
+        declare function fetchThing(): Promise<string>
+        class C {
+          getViewProps() {
+            return {
+              thing: async () => {
+                const inner = fetchThing()
+                return await inner
+              },
+            }
+          }
+        }
+      `,
+    },
+  ],
+  invalid: [
+    {
+      name: 'eager promise shared by two props',
+      filename,
+      code: `
+        declare function fetchThing(): Promise<{ a: string; b: string }>
+        class C {
+          getViewProps() {
+            const thingPromise = fetchThing()
+            return {
+              a: async () => (await thingPromise).a,
+              b: async () => (await thingPromise).b,
+            }
+          }
+        }
+      `,
+      errors: [
+        {
+          messageId: 'requireLazyPromise',
+          suggestions: [
+            {
+              messageId: 'requireLazyPromise',
+              output: `
+        declare function fetchThing(): Promise<{ a: string; b: string }>
+        class C {
+          getViewProps() {
+            const thingPromise = lazyPromise(() => fetchThing())
+            return {
+              a: async () => (await thingPromise).a,
+              b: async () => (await thingPromise).b,
+            }
+          }
+        }
+      `,
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: 'eager promise with a .catch already attached is still flagged',
+      filename,
+      code: `
+        declare function fetchThing(): Promise<string | undefined>
+        class C {
+          getViewProps() {
+            const thingPromise = fetchThing().catch(() => undefined)
+            return { thing: async () => await thingPromise }
+          }
+        }
+      `,
+      errors: [
+        {
+          messageId: 'requireLazyPromise',
+          suggestions: [
+            {
+              messageId: 'requireLazyPromise',
+              output: `
+        declare function fetchThing(): Promise<string | undefined>
+        class C {
+          getViewProps() {
+            const thingPromise = lazyPromise(() => fetchThing().catch(() => undefined))
+            return { thing: async () => await thingPromise }
+          }
+        }
+      `,
+            },
+          ],
+        },
+      ],
+    },
+  ],
+})

package/config/v3/tailwind.mjs

@@ -22,6 +22,8 @@ export function tailwindConfig(config) {
       // 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',
+      // Flags Tailwind v3 class names. The /v3 entry point targets Tailwind v4 only.
+      'better-tailwindcss/no-deprecated-classes': 'off',
     },
     settings: {
       'better-tailwindcss': { entryPoint },

package/config/v3/vueI18n.mjs

@@ -35,10 +35,12 @@ export function vueI18nConfig(config) {
         '@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.
+        // Excludes tests and stories, which don't introduce key usages beyond what
+        // source files already have, to cut the scanned file count roughly in half.
         '@intlify/vue-i18n/no-unused-keys': [
           'error',
           {
-            src: './src/{client,server,shared}/**',
+            src: './src/{client,server,shared}/**/!(*.test|*.stories).{vue,ts}',
             extensions: ['.vue', '.ts'],
             ignores: unusedKeyIgnores,
           },

package/config/v3.mjs

@@ -3,6 +3,7 @@ import { storefront } from './index.mjs'
 import { vueConfig } from './v3/vue.mjs'
 import { vueI18nConfig } from './v3/vueI18n.mjs'
 import { vueComposableConfig } from './v3/vueComposable.mjs'
+import { requireLazyPromiseConfig } from './v3/requireLazyPromise.mjs'
 import { storybookConfig } from './v3/storybook.mjs'
 import { tailwindConfig } from './v3/tailwind.mjs'
 import {
@@ -16,13 +17,22 @@ import {
  * @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.
+ *   resolver reads `paths` aliases from. Independent of `typescript.tsconfigPath`: it does not
+ *   switch on `tseslint.configs.recommendedTypeChecked` or any other `@typescript-eslint/*`
+ *   type-checked rule set. 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. Also used, with the same `?? typescript?.tsconfigPath`
+ *   fallback, by `requireLazyPromiseConfig` to type-check the `require-lazy-promise-in-view-props`
+ *   rule; when neither option resolves, that rule is omitted entirely rather than registered
+ *   without type information. Setting this DOES have one other real effect: the type
+ *   information `requireLazyPromiseConfig` attaches applies, via ESLint flat config's
+ *   per-file `languageOptions` merging, to every `.ts`/`.tsx`/`.mts`/`.cts` file in the
+ *   project (its own block matches `**\/*.ts` broadly, not just files with a `getViewProps`
+ *   method) — so `eslint-plugin-sonarjs`'s type-aware rules, which silently no-op without a
+ *   type checker, start reporting real findings project-wide the first time this option is set.
  * @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.
@@ -60,6 +70,9 @@ export const storefrontV3 = function (config) {
     ...vueConfig(vue),
     ...vueI18nConfig(i18n),
     ...vueComposableConfig(vueComposable),
+    ...requireLazyPromiseConfig(
+      resolver?.tsconfigPath ?? typescript?.tsconfigPath,
+    ),
     ...importResolverConfig(resolver?.tsconfigPath ?? typescript?.tsconfigPath),
     ...importOrderConfig(),
   )

package/config/v3.test.mjs

@@ -125,4 +125,58 @@ describe('storefrontV3', () => {
       }).toConfigs(),
     ).resolves.toBeInstanceOf(Array)
   })
+
+  it('wires the require-lazy-promise-in-view-props rule when resolver.tsconfigPath is set', async () => {
+    const config = storefrontV3({
+      tailwind: { entryPoint: './src/client/index.css' },
+      i18n: { localeDir: './src/i18n/locales/*.json' },
+      resolver: { tsconfigPath: '/absolute/resolver-tsconfig.json' },
+    })
+
+    const resolved = await config.toConfigs()
+    const entry = resolved.find(
+      (c) => c.name === 'storefront/v3/require-lazy-promise',
+    )
+    if (!entry) {
+      throw new Error('require-lazy-promise entry not found')
+    }
+    const { rules } = entry
+    if (!rules) {
+      throw new Error('require-lazy-promise entry has no rules')
+    }
+
+    expect(rules['storefront/require-lazy-promise-in-view-props']).toBe('error')
+  })
+
+  it('wires the require-lazy-promise-in-view-props rule via typescript.tsconfigPath when resolver.tsconfigPath is unset', async () => {
+    const config = storefrontV3({
+      tailwind: { entryPoint: './src/client/index.css' },
+      i18n: { localeDir: './src/i18n/locales/*.json' },
+      typescript: { tsconfigPath: '/absolute/typescript-tsconfig.json' },
+    })
+
+    const resolved = await config.toConfigs()
+    const entry = resolved.find(
+      (c) => c.name === 'storefront/v3/require-lazy-promise',
+    )
+
+    expect(entry).toBeDefined()
+  })
+
+  // Registering the rule without type information would crash ESLint's entire
+  // run on the first .ts file, rather than reporting a lint error — omitting
+  // the entry is what makes an untyped project degrade gracefully instead.
+  it('omits the require-lazy-promise-in-view-props rule entirely when no tsconfig path is resolvable', async () => {
+    const config = storefrontV3({
+      tailwind: { entryPoint: './src/client/index.css' },
+      i18n: { localeDir: './src/i18n/locales/*.json' },
+    })
+
+    const resolved = await config.toConfigs()
+    const entry = resolved.find(
+      (c) => c.name === 'storefront/v3/require-lazy-promise',
+    )
+
+    expect(entry).toBeUndefined()
+  })
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scayle/eslint-config-storefront",
-  "version": "5.1.1",
+  "version": "5.2.1",
   "description": "SCAYLE Commerce Engine specific eslint configuration",
   "author": "SCAYLE Commerce Engine",
   "license": "MIT",
@@ -42,13 +42,14 @@
     "@eslint/js": "^10.0.0",
     "@intlify/eslint-plugin-vue-i18n": "^4.5.1",
     "@scayle/eslint-plugin-vue-composable": "1.2.1",
+    "@typescript-eslint/utils": "^8.71.0",
     "@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",
+    "eslint-plugin-jsdoc": "^65.0.0",
     "eslint-plugin-jsonc": "^3.4.1",
     "eslint-plugin-n": "^18.3.0",
     "eslint-plugin-no-only-tests": "^3.4.0",
@@ -56,21 +57,23 @@
     "eslint-plugin-regexp": "^3.2.0",
     "eslint-plugin-sonarjs": "^4.2.0",
     "eslint-plugin-storybook": "^10.5.8",
-    "eslint-plugin-unicorn": "^74.0.0",
+    "eslint-plugin-unicorn": "^76.0.0",
     "eslint-plugin-vue": "^10.10.0",
     "eslint-plugin-vuejs-accessibility": "^2.6.0",
     "globals": "^17.7.0",
-    "typescript-eslint": "^8.67.0",
+    "ts-api-utils": "^2.1.2",
+    "typescript-eslint": "^8.71.0",
     "vue-eslint-parser": "^10.4.1"
   },
   "devDependencies": {
     "@types/node": "^24",
-    "@vitest/coverage-v8": "4.1.11",
-    "eslint": "10.9.1",
+    "@typescript-eslint/rule-tester": "^8.71.0",
+    "@vitest/coverage-v8": "5.0.3",
+    "eslint": "10.11.0",
     "eslint-formatter-gitlab": "7.2.0",
     "publint": "0.3.24",
     "typescript": "6.0.3",
-    "vitest": "4.1.11"
+    "vitest": "5.0.3"
   },
   "scripts": {
     "lint": "eslint .",