feat(sfcc): validate */ and ~/ require paths against filesystem existence

extend sfcc/valid-require-path with optional existence checks for */ and ~/
add optional cartridgePath ordering for */ resolution
extend tests for valid/invalid star and tilde references
update README docs for the new options

Author: jenssimon

README.md

@@ -83,7 +83,7 @@ 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` |
+| `sfcc/valid-require-path`   | Validates SFCC-compatible `require()` paths (`dw/*`, `cartridgeName/*`, `./*`, `../*`, `*/*`, `~/*`) and supports optional filesystem existence checks. | `error` |
 
 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`.
 
@@ -102,10 +102,12 @@ export default defineConfig(sfcc.configs.recommended, {
       {
         // Optional: allow additional bare module ids
         allowBareModules: ["server", "proxyquire"],
-        // Optional: verify cartridgeName/* against filesystem
+        // 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"],
       },
     ],
   },

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

@@ -7,8 +7,11 @@ type RuleOptions = {
   allowBareModules?: string[]
   checkCartridgeExists?: boolean
   cartridgesDir?: string
+  cartridgePath?: string[]
 }
 
+const SUPPORTED_EXTENSIONS = ["js", "ds", "json"]
+
 function getStringArgument(node: Rule.Node): string | undefined {
   if (node.type === "Literal" && typeof node.value === "string") {
     return node.value
@@ -44,6 +47,101 @@ function resolveCartridgesDir(cartridgesDir: string, cwd: string): string {
   return path.isAbsolute(cartridgesDir) ? cartridgesDir : path.resolve(cwd, cartridgesDir)
 }
 
+function getConfiguredCartridgePath(cartridgePath: string[] | undefined): string[] {
+  if (!cartridgePath) {
+    return []
+  }
+
+  return cartridgePath.filter((entry) => entry.trim().length > 0)
+}
+
+function getFilesystemCartridges(cartridgesDir: string, cwd: string): string[] {
+  const baseDir = resolveCartridgesDir(cartridgesDir, cwd)
+
+  try {
+    return fs
+      .readdirSync(baseDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+  } catch {
+    return []
+  }
+}
+
+function moduleExistsInCartridge(
+  cartridgeName: string,
+  moduleTarget: string,
+  cartridgesDir: string,
+  cwd: string,
+): boolean {
+  const baseDir = resolveCartridgesDir(cartridgesDir, cwd)
+  const normalizedTarget = moduleTarget.replace(/^\/+/, "")
+  const targetPath = path.join(baseDir, cartridgeName, normalizedTarget)
+
+  if (path.extname(normalizedTarget)) {
+    return fs.existsSync(targetPath)
+  }
+
+  return SUPPORTED_EXTENSIONS.some((extension) => fs.existsSync(`${targetPath}.${extension}`))
+}
+
+function getOwnCartridge(filename: string, cartridgesDir: string, cwd: string): string | undefined {
+  if (filename === "<input>") {
+    return undefined
+  }
+
+  const resolvedFilename = path.isAbsolute(filename) ? filename : path.resolve(cwd, filename)
+  const baseDir = resolveCartridgesDir(cartridgesDir, cwd)
+  const relativePath = path.relative(baseDir, resolvedFilename)
+
+  if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    return undefined
+  }
+
+  const firstSegment = relativePath.split(path.sep)[0]
+  return firstSegment && firstSegment !== "." ? firstSegment : undefined
+}
+
+function starReferenceExists(
+  requirePath: string,
+  cartridgesDir: string,
+  cwd: string,
+  configuredCartridgePath: string[],
+): boolean {
+  const moduleTarget = requirePath.slice(2)
+  if (!moduleTarget) {
+    return false
+  }
+
+  const cartridgeNames =
+    configuredCartridgePath.length > 0
+      ? configuredCartridgePath
+      : getFilesystemCartridges(cartridgesDir, cwd)
+
+  return cartridgeNames.some((name) =>
+    moduleExistsInCartridge(name, moduleTarget, cartridgesDir, cwd),
+  )
+}
+
+function tildeReferenceExists(
+  requirePath: string,
+  filename: string,
+  cartridgesDir: string,
+  cwd: string,
+): boolean {
+  const moduleTarget = requirePath.slice(2)
+  if (!moduleTarget) {
+    return false
+  }
+
+  const ownCartridge = getOwnCartridge(filename, cartridgesDir, cwd)
+  if (!ownCartridge) {
+    return false
+  }
+
+  return moduleExistsInCartridge(ownCartridge, moduleTarget, cartridgesDir, cwd)
+}
+
 function cartridgeExists(cartridgeName: string, cartridgesDir: string, cwd: string): boolean {
   const baseDir = resolveCartridgesDir(cartridgesDir, cwd)
   const cartridgeRoot = path.join(baseDir, cartridgeName)
@@ -74,6 +172,11 @@ const validRequirePath: Rule.RuleModule = {
           },
           checkCartridgeExists: { type: "boolean" },
           cartridgesDir: { type: "string" },
+          cartridgePath: {
+            type: "array",
+            items: { type: "string" },
+            uniqueItems: true,
+          },
         },
         additionalProperties: false,
       },
@@ -83,17 +186,26 @@ const validRequirePath: Rule.RuleModule = {
         'Invalid require path "{{requirePath}}". Allowed: dw/*, cartridgeName/*, ./*, ../*, */*, ~/* or configured bare modules.',
       unknownCartridge:
         'Unknown cartridge "{{cartridgeName}}" in require path "{{requirePath}}" (checked in "{{cartridgesDir}}/").',
+      unresolvedStarPath:
+        'Cannot resolve "{{requirePath}}" against configured cartridges in "{{cartridgesDir}}/".',
+      unresolvedTildePath:
+        'Cannot resolve "{{requirePath}}" in current cartridge (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 configuredCartridgePath = getConfiguredCartridgePath(options.cartridgePath)
     const cwd =
       (context as Rule.RuleContext & { cwd?: string }).cwd ??
       (context as Rule.RuleContext & { getCwd?: () => string }).getCwd?.() ??
       process.cwd()
+    const filename =
+      (context as Rule.RuleContext & { filename?: string }).filename ??
+      (context as Rule.RuleContext & { getFilename?: () => string }).getFilename?.() ??
+      "<input>"
 
     return {
       CallExpression(node) {
@@ -116,6 +228,34 @@ const validRequirePath: Rule.RuleModule = {
           return
         }
 
+        if (requirePath.startsWith("*/")) {
+          if (
+            checkCartridgeExists &&
+            !starReferenceExists(requirePath, cartridgesDir, cwd, configuredCartridgePath)
+          ) {
+            context.report({
+              node: firstArgument,
+              messageId: "unresolvedStarPath",
+              data: { requirePath, cartridgesDir },
+            })
+          }
+          return
+        }
+
+        if (requirePath.startsWith("~/")) {
+          if (
+            checkCartridgeExists &&
+            !tildeReferenceExists(requirePath, filename, cartridgesDir, cwd)
+          ) {
+            context.report({
+              node: firstArgument,
+              messageId: "unresolvedTildePath",
+              data: { requirePath, cartridgesDir },
+            })
+          }
+          return
+        }
+
         if (isAllowedPrefix(requirePath)) {
           return
         }

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

@@ -1,6 +1,5 @@
 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"
 
@@ -78,11 +77,23 @@ test("ignores dynamic requires", () => {
 })
 
 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 testSuffix = `${Date.now()}_${Math.floor(Math.random() * 1_000_000)}`
+  const existingCartridgeName = `app_storefront_${testSuffix}`
+  const ownCartridgeName = `app_sfra_${testSuffix}`
+  const cartridgesDir = path.join(process.cwd(), "cartridges")
+  const existingCartridge = path.join(cartridgesDir, existingCartridgeName)
+  const ownCartridge = path.join(cartridgesDir, ownCartridgeName)
+
+  fs.mkdirSync(path.join(existingCartridge, "cartridge", "scripts"), { recursive: true })
+  fs.mkdirSync(path.join(ownCartridge, "cartridge", "scripts"), { recursive: true })
+  fs.writeFileSync(
+    path.join(existingCartridge, "cartridge", "scripts", "ok.js"),
+    "module.exports = true",
+  )
+  fs.writeFileSync(
+    path.join(ownCartridge, "cartridge", "scripts", "local.js"),
+    "module.exports = true",
+  )
 
   const linter = new Linter()
   const config: Linter.Config[] = [
@@ -94,7 +105,7 @@ test("supports checkCartridgeExists option", () => {
           "error",
           {
             checkCartridgeExists: true,
-            cartridgesDir,
+            cartridgesDir: "cartridges",
           },
         ],
       },
@@ -103,17 +114,24 @@ test("supports checkCartridgeExists option", () => {
 
   const messages = linter.verify(
     `
-      const ok = require("app_storefront/cartridge/scripts/ok")
+      const ok = require("${existingCartridgeName}/cartridge/scripts/ok")
+      const okStar = require("*/cartridge/scripts/ok")
+      const okTilde = require("~/cartridge/scripts/local")
       const bad = require("missing_cartridge/cartridge/scripts/bad")
-      module.exports = { ok, bad }
+      const badStar = require("*/cartridge/scripts/does-not-exist")
+      const badTilde = require("~/cartridge/scripts/does-not-exist")
+      module.exports = { ok, okStar, okTilde, bad, badStar, badTilde }
     `,
     config,
-    { filename: "cartridges/app_sfra/cartridge/controllers/Home.js" },
+    { filename: `cartridges/${ownCartridgeName}/cartridge/controllers/Home.js` },
   )
 
-  fs.rmSync(tempRoot, { recursive: true, force: true })
+  fs.rmSync(existingCartridge, { recursive: true, force: true })
+  fs.rmSync(ownCartridge, { recursive: true, force: true })
 
   const hits = messages.filter((m) => m.ruleId === "sfcc/valid-require-path")
-  expect(hits).toHaveLength(1)
+  expect(hits).toHaveLength(3)
   expect(hits[0]?.message.includes("missing_cartridge")).toBe(true)
+  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)
 })