feat(sfcc): add valid-require-path rule for SFCC module imports

add new sfcc rule to validate require path patterns
allow SFCC-specific forms: dw/, cartridgeName/, ./, ../, */, ~/
keep optional cartridge existence check via rule options
register and enable rule in recommended config
add tests for allowed, invalid, dynamic, and existence-check scenarios
document rule behavior and configuration in README

Author: jenssimon

README.md

@@ -83,8 +83,34 @@ The new `sfcc` plugin contains the general Rhino/SFCC runtime rules:
 | `sfcc/prefer-const`         | Requires `const` for `let` declarations that are never reassigned, excluding Rhino-sensitive nested/loop contexts.                                      | `error` |
 | `sfcc/rhino-const-compat`   | Enforces `let` instead of `const` in Rhino loop-critical contexts (loop headers and declarations inside loop bodies) and supports auto-fix.             | `error` |
 | `sfcc/rhino-const-conflict` | Detects same-name `const` declarations in nested blocks within the same function (Rhino treats them as function-scoped) and supports auto-fix to `let`. | `error` |
+| `sfcc/valid-require-path`   | Validates SFCC-compatible `require()` paths (`dw/*`, `cartridgeName/*`, `./*`, `../*`, `*/*`, `~/*`) and supports optional cartridge-existence checks.  | `error` |
 
-The recommended config intentionally combines these three `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`.
+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
+
+By default, the rule validates path patterns only and allows bare `server` requires.
+
+```js
+import { defineConfig } from "eslint/config"
+import sfcc 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/* against filesystem
+        checkCartridgeExists: true,
+        // Optional: absolute or relative path to cartridges root
+        cartridgesDir: "cartridges",
+      },
+    ],
+  },
+})
+```
 
 ### Rhino const strategy example
 

src/plugins/sfcc/index.ts

@@ -1,12 +1,14 @@
 import preferConst from "./prefer-const.js"
 import rhinoConstCompat from "./rhino-const-compat.js"
 import rhinoConstConflict from "./rhino-const-conflict.js"
+import validRequirePath from "./valid-require-path.js"
 
 const sfcc = {
   rules: {
     "prefer-const": preferConst,
     "rhino-const-compat": rhinoConstCompat,
     "rhino-const-conflict": rhinoConstConflict,
+    "valid-require-path": validRequirePath,
   },
 }
 

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

@@ -0,0 +1,160 @@
+import type { Rule } from "eslint"
+
+import fs from "node:fs"
+import path from "node:path"
+
+type RuleOptions = {
+  allowBareModules?: string[]
+  checkCartridgeExists?: boolean
+  cartridgesDir?: string
+}
+
+function getStringArgument(node: Rule.Node): string | undefined {
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return node.value
+  }
+
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) {
+    return node.quasis[0]?.value.cooked ?? undefined
+  }
+
+  return undefined
+}
+
+function isAllowedPrefix(requirePath: string): boolean {
+  return (
+    requirePath.startsWith("dw/") ||
+    requirePath.startsWith("./") ||
+    requirePath.startsWith("../") ||
+    requirePath.startsWith("*/") ||
+    requirePath.startsWith("~/")
+  )
+}
+
+function isCartridgeStylePath(requirePath: string): boolean {
+  return /^[A-Za-z0-9_-]+\/.+/u.test(requirePath)
+}
+
+function getFirstSegment(requirePath: string): string {
+  const slashIndex = requirePath.indexOf("/")
+  return slashIndex === -1 ? requirePath : requirePath.slice(0, slashIndex)
+}
+
+function resolveCartridgesDir(cartridgesDir: string, cwd: string): string {
+  return path.isAbsolute(cartridgesDir) ? cartridgesDir : path.resolve(cwd, cartridgesDir)
+}
+
+function cartridgeExists(cartridgeName: string, cartridgesDir: string, cwd: string): boolean {
+  const baseDir = resolveCartridgesDir(cartridgesDir, cwd)
+  const cartridgeRoot = path.join(baseDir, cartridgeName)
+
+  try {
+    return fs.statSync(cartridgeRoot).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+const validRequirePath: Rule.RuleModule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "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" },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      invalidPath:
+        'Invalid require path "{{requirePath}}". Allowed: dw/*, cartridgeName/*, ./*, ../*, */*, ~/* or configured bare modules.',
+      unknownCartridge:
+        'Unknown cartridge "{{cartridgeName}}" in require path "{{requirePath}}" (checked in "{{cartridgesDir}}/").',
+    },
+  },
+  create: (context) => {
+    const options = (context.options[0] ?? {}) as RuleOptions
+    const allowBareModules = new Set(options.allowBareModules ?? ["server"])
+    const checkCartridgeExists = options.checkCartridgeExists === true
+    const cartridgesDir = options.cartridgesDir ?? "cartridges"
+    const cwd =
+      (context as Rule.RuleContext & { cwd?: string }).cwd ??
+      (context as Rule.RuleContext & { getCwd?: () => string }).getCwd?.() ??
+      process.cwd()
+
+    return {
+      CallExpression(node) {
+        const callNode = node as Rule.Node & {
+          callee?: { type?: string; name?: string }
+          arguments?: Rule.Node[]
+        }
+
+        if (callNode.callee?.type !== "Identifier" || callNode.callee.name !== "require") {
+          return
+        }
+
+        const firstArgument = callNode.arguments?.[0]
+        if (!firstArgument) {
+          return
+        }
+
+        const requirePath = getStringArgument(firstArgument)
+        if (!requirePath) {
+          return
+        }
+
+        if (isAllowedPrefix(requirePath)) {
+          return
+        }
+
+        if (!requirePath.includes("/")) {
+          if (!allowBareModules.has(requirePath)) {
+            context.report({
+              node: firstArgument,
+              messageId: "invalidPath",
+              data: { requirePath },
+            })
+          }
+          return
+        }
+
+        if (!isCartridgeStylePath(requirePath)) {
+          context.report({
+            node: firstArgument,
+            messageId: "invalidPath",
+            data: { requirePath },
+          })
+          return
+        }
+
+        if (!checkCartridgeExists) {
+          return
+        }
+
+        const cartridgeName = getFirstSegment(requirePath)
+        if (!cartridgeExists(cartridgeName, cartridgesDir, cwd)) {
+          context.report({
+            node: firstArgument,
+            messageId: "unknownCartridge",
+            data: { cartridgeName, requirePath, cartridgesDir },
+          })
+        }
+      },
+    }
+  },
+}
+
+export default validRequirePath

src/rules/sfcc.ts

@@ -4,6 +4,7 @@ const sfcc: Linter.RulesRecord = {
   "sfcc/prefer-const": "error",
   "sfcc/rhino-const-compat": "error",
   "sfcc/rhino-const-conflict": "error",
+  "sfcc/valid-require-path": "error",
 }
 
 export default sfcc

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

@@ -0,0 +1,119 @@
+import { Linter } from "eslint"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { expect, test } from "vite-plus/test"
+
+import { recommended } from "../src/index.js"
+
+function lint(code: string, filename = "cartridges/app_sfra/cartridge/controllers/Home.js") {
+  const linter = new Linter()
+  return linter.verify(code, recommended, { filename })
+}
+
+test("allows dw requires", () => {
+  const messages = lint(`
+    const OrderMgr = require("dw/order/OrderMgr")
+    module.exports = OrderMgr
+  `)
+
+  expect(messages.some((m) => m.ruleId === "sfcc/valid-require-path")).toBe(false)
+})
+
+test("allows cartridge-style requires", () => {
+  const messages = lint(`
+    const helper = require("app_storefront/cartridge/scripts/helper")
+    module.exports = helper
+  `)
+
+  expect(messages.some((m) => m.ruleId === "sfcc/valid-require-path")).toBe(false)
+})
+
+test("allows relative requires", () => {
+  const messages = lint(`
+    const one = require("./test")
+    const two = require("../test")
+    module.exports = { one, two }
+  `)
+
+  expect(messages.some((m) => m.ruleId === "sfcc/valid-require-path")).toBe(false)
+})
+
+test("allows SFCC star and tilde requires", () => {
+  const messages = lint(`
+    const one = require("*/cartridge/scripts/middleware/csrf")
+    const two = require("~/cartridge/scripts/middleware/auth")
+    module.exports = { one, two }
+  `)
+
+  expect(messages.some((m) => m.ruleId === "sfcc/valid-require-path")).toBe(false)
+})
+
+test("allows configured default bare module server", () => {
+  const messages = lint(`
+    const server = require("server")
+    module.exports = server
+  `)
+
+  expect(messages.some((m) => m.ruleId === "sfcc/valid-require-path")).toBe(false)
+})
+
+test("reports invalid bare module requires", () => {
+  const messages = lint(`
+    const lodash = require("lodash")
+    module.exports = lodash
+  `)
+
+  expect(messages.some((m) => m.ruleId === "sfcc/valid-require-path")).toBe(true)
+})
+
+test("ignores dynamic requires", () => {
+  const messages = lint(`
+    const moduleName = "dw/order/OrderMgr"
+    const dynamic = require(moduleName)
+    module.exports = dynamic
+  `)
+
+  expect(messages.some((m) => m.ruleId === "sfcc/valid-require-path")).toBe(false)
+})
+
+test("supports checkCartridgeExists option", () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "eslint-config-sfcc-"))
+  const cartridgesDir = path.join(tempRoot, "cartridges")
+  const existingCartridge = path.join(cartridgesDir, "app_storefront")
+
+  fs.mkdirSync(existingCartridge, { recursive: true })
+
+  const linter = new Linter()
+  const config: Linter.Config[] = [
+    {
+      ...recommended[0],
+      rules: {
+        ...recommended[0]?.rules,
+        "sfcc/valid-require-path": [
+          "error",
+          {
+            checkCartridgeExists: true,
+            cartridgesDir,
+          },
+        ],
+      },
+    },
+  ]
+
+  const messages = linter.verify(
+    `
+      const ok = require("app_storefront/cartridge/scripts/ok")
+      const bad = require("missing_cartridge/cartridge/scripts/bad")
+      module.exports = { ok, bad }
+    `,
+    config,
+    { filename: "cartridges/app_sfra/cartridge/controllers/Home.js" },
+  )
+
+  fs.rmSync(tempRoot, { recursive: true, force: true })
+
+  const hits = messages.filter((m) => m.ruleId === "sfcc/valid-require-path")
+  expect(hits).toHaveLength(1)
+  expect(hits[0]?.message.includes("missing_cartridge")).toBe(true)
+})