refactor(sfcc): centralize shared settings handling across sfcc rules

extract shared sfcc settings access into reusable utilities
apply withSfccSettings consistently across sfcc rules
keep runtime behavior unchanged
align tests and docs with the shared settings pattern

Author: jenssimon

README.md

@@ -51,6 +51,11 @@ import { createRecommendedConfig } from "@jenssimon/eslint-config-sfcc"
 export default defineConfig(
   createRecommendedConfig({
     cartridgesDir: "cartridges/",
+    sfcc: {
+      checkCartridgeExists: true,
+      allowBareModules: ["server", "proxyquire"],
+      cartridgePath: ["app_storefront", "modules", "app_custom"],
+    },
   }),
 )
 ```
@@ -87,31 +92,29 @@ The new `sfcc` plugin contains the general Rhino/SFCC runtime rules:
 
 The recommended config intentionally combines these `sfcc/*` rules so `--fix` does not bounce between conflicting suggestions: Rhino-unsafe `const` becomes `let`, while genuinely safe top-level function bindings still become `const`.
 
-### `sfcc/valid-require-path` options
+### Shared `sfcc` options (including `sfcc/valid-require-path`)
 
-By default, the rule validates path patterns only and allows bare `server` requires.
+By default, `sfcc/valid-require-path` validates path patterns only and allows bare `server` requires.
+
+Use `createRecommendedConfig({ sfcc: ... })` to define shared SFCC plugin options centrally. These values are exposed through ESLint `settings.sfcc`, so future `sfcc/*` rules can reuse them without adding per-rule options.
 
 ```js
 import { defineConfig } from "eslint/config"
-import sfcc from "@jenssimon/eslint-config-sfcc"
+import { createRecommendedConfig } from "@jenssimon/eslint-config-sfcc"
 
-export default defineConfig(sfcc.configs.recommended, {
-  rules: {
-    "sfcc/valid-require-path": [
-      "error",
-      {
-        // Optional: allow additional bare module ids
-        allowBareModules: ["server", "proxyquire"],
-        // Optional: verify cartridgeName/* plus */* and ~/* against filesystem
-        checkCartridgeExists: true,
-        // Optional: absolute or relative path to cartridges root
-        cartridgesDir: "cartridges",
-        // Optional: explicit cartridge order for */* lookup (otherwise folders in cartridgesDir are used)
-        cartridgePath: ["app_storefront", "modules", "app_custom"],
-      },
-    ],
-  },
-})
+export default defineConfig(
+  createRecommendedConfig({
+    cartridgesDir: "cartridges",
+    sfcc: {
+      // Optional: allow additional bare module ids
+      allowBareModules: ["server", "proxyquire"],
+      // Optional: verify cartridgeName/* plus */* and ~/* against filesystem
+      checkCartridgeExists: true,
+      // Optional: explicit cartridge order for */* lookup (otherwise folders in cartridgesDir are used)
+      cartridgePath: ["app_storefront", "modules", "app_custom"],
+    },
+  }),
+)
 ```
 
 ### Rhino const strategy example

src/configs/recommended.ts

@@ -4,6 +4,8 @@ import { fixupPluginRules } from "@eslint/compat"
 import es from "eslint-plugin-es"
 import globals from "globals"
 
+import type { SfccSettings } from "../types/sfcc-settings.js"
+
 import sfcc from "../plugins/sfcc/index.js"
 import sitegenesis from "../plugins/sitegenesis/index.js"
 import rules from "../rules/index.js"
@@ -16,12 +18,29 @@ export interface RecommendedConfigOptions {
   files?: string[]
   /** Optional override for ignore globs. */
   ignores?: string[]
+  /** Optional shared options for sfcc rules. */
+  sfcc?: SfccSettings
 }
 
 /** Creates the recommended flat config for SFCC projects. */
 export function createRecommendedConfig(options: RecommendedConfigOptions = {}): Linter.Config[] {
-  const { cartridgesDir = "cartridges", files, ignores } = options
+  const { cartridgesDir = "cartridges", files, ignores, sfcc: sfccOptions } = options
   const normalizedCartridgesDir = cartridgesDir.replace(/\/+$/u, "") || "/"
+  const hasSfccOptions =
+    sfccOptions !== undefined &&
+    (sfccOptions.allowBareModules !== undefined ||
+      sfccOptions.checkCartridgeExists !== undefined ||
+      sfccOptions.cartridgePath !== undefined ||
+      sfccOptions.cartridgesDir !== undefined)
+
+  const sfccSettings: SfccSettings | undefined = hasSfccOptions
+    ? {
+        ...sfccOptions,
+        ...(sfccOptions?.cartridgesDir === undefined
+          ? { cartridgesDir: normalizedCartridgesDir }
+          : {}),
+      }
+    : undefined
 
   function withBaseDir(suffix: string): string {
     return normalizedCartridgesDir === "/" ? `/${suffix}` : `${normalizedCartridgesDir}/${suffix}`
@@ -46,6 +65,7 @@ export function createRecommendedConfig(options: RecommendedConfigOptions = {}):
         sfcc,
         sitegenesis,
       },
+      ...(sfccSettings === undefined ? {} : { settings: { sfcc: sfccSettings } }),
       rules,
     },
   ]

src/plugins/_utils/sfcc-settings.ts

@@ -0,0 +1,17 @@
+import type { Rule } from "eslint"
+
+import type { SfccSettings } from "../../types/sfcc-settings.js"
+
+type RuleContextWithSettings = Rule.RuleContext & {
+  settings?: { sfcc?: SfccSettings }
+}
+
+export function getSfccSettings(context: Rule.RuleContext): SfccSettings {
+  return (context as RuleContextWithSettings).settings?.sfcc ?? {}
+}
+
+export function withSfccSettings(
+  createWithSettings: (context: Rule.RuleContext, sfccSettings: SfccSettings) => Rule.RuleListener,
+): (context: Rule.RuleContext) => Rule.RuleListener {
+  return (context) => createWithSettings(context, getSfccSettings(context))
+}

src/plugins/sfcc/prefer-const.ts

@@ -1,6 +1,7 @@
 import type { Rule, Scope } from "eslint"
 
 import { isInNestedBlock, isRhinoCriticalScope } from "../_utils/rhino-scope.js"
+import { withSfccSettings } from "../_utils/sfcc-settings.js"
 
 function isNeverReassigned(variable: Scope.Variable): boolean {
   // A variable is "never reassigned" if all its write references are the
@@ -23,7 +24,7 @@ const preferConst: Rule.RuleModule = {
       useConst: "Prefer const over {{kind}} when the variable is never reassigned.",
     },
   },
-  create: (context) => {
+  create: withSfccSettings((context) => {
     function checkDeclaration(node: Rule.Node) {
       // In Rhino-critical scopes const is broken — don't suggest it here.
       // In any nested block, const might cause Rhino re-declaration conflicts.
@@ -85,7 +86,7 @@ const preferConst: Rule.RuleModule = {
       "VariableDeclaration[kind='let']": checkDeclaration,
       "VariableDeclaration[kind='var']": checkVarDeclaration,
     }
-  },
+  }),
 }
 
 export default preferConst

src/plugins/sfcc/rhino-const-compat.ts

@@ -1,6 +1,7 @@
 import type { Rule } from "eslint"
 
 import { isRhinoCriticalScope } from "../_utils/rhino-scope.js"
+import { withSfccSettings } from "../_utils/sfcc-settings.js"
 
 function isRhinoCriticalConstDeclaration(node: Rule.Node): boolean {
   return node.type === "VariableDeclaration" && node.kind === "const" && isRhinoCriticalScope(node)
@@ -19,7 +20,7 @@ const rhinoConstCompat: Rule.RuleModule = {
       useLet: "Use let instead of const in this block-scoped context for Rhino compatibility.",
     },
   },
-  create: (context) => ({
+  create: withSfccSettings((context) => ({
     VariableDeclaration(node) {
       if (!isRhinoCriticalConstDeclaration(node as Rule.Node)) {
         return
@@ -38,7 +39,7 @@ const rhinoConstCompat: Rule.RuleModule = {
         },
       })
     },
-  }),
+  })),
 }
 
 export default rhinoConstCompat

src/plugins/sfcc/rhino-const-conflict.ts

@@ -1,6 +1,7 @@
 import type { Rule } from "eslint"
 
 import { isInNestedBlock } from "../_utils/rhino-scope.js"
+import { withSfccSettings } from "../_utils/sfcc-settings.js"
 
 interface FuncScope {
   /** All const declarations per identifier name (function-level + nested). */
@@ -24,7 +25,7 @@ const rhinoConstConflict: Rule.RuleModule = {
         "'{{name}}' is declared as const in multiple block scopes of the same function. Use let to avoid a Rhino re-declaration error.",
     },
   },
-  create: (context) => {
+  create: withSfccSettings((context) => {
     const stack: FuncScope[] = []
 
     function enterFunction(): void {
@@ -82,7 +83,7 @@ const rhinoConstConflict: Rule.RuleModule = {
         }
       },
     }
-  },
+  }),
 }
 
 export default rhinoConstConflict

src/plugins/sfcc/valid-require-path.ts

@@ -3,12 +3,7 @@ import type { Rule } from "eslint"
 import fs from "node:fs"
 import path from "node:path"
 
-type RuleOptions = {
-  allowBareModules?: string[]
-  checkCartridgeExists?: boolean
-  cartridgesDir?: string
-  cartridgePath?: string[]
-}
+import { withSfccSettings } from "../_utils/sfcc-settings.js"
 
 const SUPPORTED_EXTENSIONS = ["js", "ds", "json"]
 
@@ -161,26 +156,8 @@ const validRequirePath: Rule.RuleModule = {
         "Enforce SFCC-compatible require paths (dw/, relative, cartridge-name/, */, ~/).",
       recommended: true,
     },
-    schema: [
-      {
-        type: "object",
-        properties: {
-          allowBareModules: {
-            type: "array",
-            items: { type: "string" },
-            uniqueItems: true,
-          },
-          checkCartridgeExists: { type: "boolean" },
-          cartridgesDir: { type: "string" },
-          cartridgePath: {
-            type: "array",
-            items: { type: "string" },
-            uniqueItems: true,
-          },
-        },
-        additionalProperties: false,
-      },
-    ],
+    // Shared sfcc configuration is provided via ESLint settings.sfcc.
+    schema: [],
     messages: {
       invalidPath:
         'Invalid require path "{{requirePath}}". Allowed: dw/*, cartridgeName/*, ./*, ../*, */*, ~/* or configured bare modules.',
@@ -192,8 +169,7 @@ const validRequirePath: Rule.RuleModule = {
         'Cannot resolve "{{requirePath}}" in current cartridge (checked in "{{cartridgesDir}}/").',
     },
   },
-  create: (context) => {
-    const options = (context.options[0] ?? {}) as RuleOptions
+  create: withSfccSettings((context, options) => {
     const allowBareModules = new Set(options.allowBareModules ?? ["server"])
     const checkCartridgeExists = options.checkCartridgeExists === true
     const cartridgesDir = options.cartridgesDir ?? "cartridges"
@@ -294,7 +270,7 @@ const validRequirePath: Rule.RuleModule = {
         }
       },
     }
-  },
+  }),
 }
 
 export default validRequirePath

src/types/sfcc-settings.ts

@@ -0,0 +1,6 @@
+export interface SfccSettings {
+  allowBareModules?: string[]
+  checkCartridgeExists?: boolean
+  cartridgesDir?: string
+  cartridgePath?: string[]
+}

tests/index.test.ts

@@ -33,6 +33,25 @@ test("accepts cartridgesDir with trailing slash", () => {
   expect(createdConfig).toEqual(recommended)
 })
 
+test("forwards shared sfcc options via settings", () => {
+  const createdConfig = createRecommendedConfig({
+    cartridgesDir: "custom-cartridges",
+    sfcc: {
+      checkCartridgeExists: true,
+      cartridgePath: ["app_storefront", "modules"],
+    },
+  })
+
+  expect(createdConfig[0]?.settings).toEqual({
+    sfcc: {
+      checkCartridgeExists: true,
+      cartridgePath: ["app_storefront", "modules"],
+      cartridgesDir: "custom-cartridges",
+    },
+  })
+  expect(createdConfig[0]?.rules?.["sfcc/valid-require-path"]).toBe("error")
+})
+
 test("exports sitegenesis plugin", () => {
   expect(sitegenesis).toBe(plugins.sitegenesis)
 })

tests/sfcc-valid-require-path.test.ts

@@ -3,7 +3,7 @@ import fs from "node:fs"
 import path from "node:path"
 import { expect, test } from "vite-plus/test"
 
-import { recommended } from "../src/index.js"
+import { createRecommendedConfig, recommended } from "../src/index.js"
 
 function lint(code: string, filename = "cartridges/app_sfra/cartridge/controllers/Home.js") {
   const linter = new Linter()
@@ -96,21 +96,12 @@ test("supports checkCartridgeExists option", () => {
   )
 
   const linter = new Linter()
-  const config: Linter.Config[] = [
-    {
-      ...recommended[0],
-      rules: {
-        ...recommended[0]?.rules,
-        "sfcc/valid-require-path": [
-          "error",
-          {
-            checkCartridgeExists: true,
-            cartridgesDir: "cartridges",
-          },
-        ],
-      },
+  const config = createRecommendedConfig({
+    cartridgesDir: "cartridges",
+    sfcc: {
+      checkCartridgeExists: true,
     },
-  ]
+  })
 
   const messages = linter.verify(
     `
@@ -135,3 +126,23 @@ test("supports checkCartridgeExists option", () => {
   expect(hits.some((m) => m.message.includes("*/cartridge/scripts/does-not-exist"))).toBe(true)
   expect(hits.some((m) => m.message.includes("~/cartridge/scripts/does-not-exist"))).toBe(true)
 })
+
+test("rejects direct rule options and requires shared settings", () => {
+  const linter = new Linter()
+
+  const config: Linter.Config[] = [
+    {
+      ...recommended[0],
+      rules: {
+        ...recommended[0]?.rules,
+        "sfcc/valid-require-path": ["error", { checkCartridgeExists: true }],
+      },
+    },
+  ]
+
+  expect(() =>
+    linter.verify('const x = require("server"); module.exports = x', config, {
+      filename: "cartridges/app_sfra/cartridge/controllers/Home.js",
+    }),
+  ).toThrow()
+})