feat(sfcc): add site template cartridge resolution via site setting

support resolving custom-cartridges from <siteTemplatePath>/sites/<site>/site.xml
use lightweight XML parsing with fast-xml-parser
extract site-template cartridge-path logic into a shared utility
add dedicated utility tests and update valid-require-path tests

Author: jenssimon

README.md

@@ -92,7 +92,7 @@ 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`.
 
-### Shared `sfcc` options (including `sfcc/valid-require-path`)
+### Shared `sfcc` options
 
 By default, `sfcc/valid-require-path` validates path patterns only and allows bare `server` requires.
 
@@ -112,6 +112,10 @@ export default defineConfig(
       checkCartridgeExists: true,
       // Optional: explicit cartridge order for */* lookup (otherwise folders in cartridgesDir are used)
       cartridgePath: ["app_storefront", "modules", "app_custom"],
+      // Optional: path to site template directory
+      siteTemplatePath: "sites/site_template",
+      // Optional: site id under <siteTemplatePath>/sites/<site>/site.xml
+      site: "example",
     },
   }),
 )

package.json

@@ -41,7 +41,8 @@
     "semantic-release": "semantic-release"
   },
   "dependencies": {
-    "eslint-plugin-es": "^4.1.0"
+    "eslint-plugin-es": "^4.1.0",
+    "fast-xml-parser": "^5.8.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

pnpm-lock.yaml

@@ -31,7 +31,9 @@ export function createRecommendedConfig(options: RecommendedConfigOptions = {}):
     (sfccOptions.allowBareModules !== undefined ||
       sfccOptions.checkCartridgeExists !== undefined ||
       sfccOptions.cartridgePath !== undefined ||
-      sfccOptions.cartridgesDir !== undefined)
+      sfccOptions.cartridgesDir !== undefined ||
+      sfccOptions.siteTemplatePath !== undefined ||
+      sfccOptions.site !== undefined)
 
   const sfccSettings: SfccSettings | undefined = hasSfccOptions
     ? {

src/configs/recommended.ts

@@ -0,0 +1,84 @@
+import { XMLParser } from "fast-xml-parser"
+import fs from "node:fs"
+import path from "node:path"
+
+function resolveSiteTemplateXmlPath(
+  siteTemplatePath: string | undefined,
+  site: string | undefined,
+  cwd: string,
+): string | undefined {
+  if (!siteTemplatePath || !site) {
+    return undefined
+  }
+
+  const resolvedSiteTemplatePath = path.isAbsolute(siteTemplatePath)
+    ? siteTemplatePath
+    : path.resolve(cwd, siteTemplatePath)
+
+  return path.join(resolvedSiteTemplatePath, "sites", site, "site.xml")
+}
+
+function findCustomCartridges(value: unknown): string | undefined {
+  if (!value || typeof value !== "object") {
+    return undefined
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = findCustomCartridges(item)
+      if (found) {
+        return found
+      }
+    }
+    return undefined
+  }
+
+  const objectValue = value as Record<string, unknown>
+  const directValue = objectValue["custom-cartridges"]
+  if (typeof directValue === "string") {
+    return directValue
+  }
+
+  for (const nestedValue of Object.values(objectValue)) {
+    const found = findCustomCartridges(nestedValue)
+    if (found) {
+      return found
+    }
+  }
+
+  return undefined
+}
+
+export function getSiteTemplateCartridgePath(
+  siteTemplatePath: string | undefined,
+  site: string | undefined,
+  cwd: string,
+): string[] {
+  const siteTemplateXmlPath = resolveSiteTemplateXmlPath(siteTemplatePath, site, cwd)
+  if (!siteTemplateXmlPath) {
+    return []
+  }
+
+  try {
+    const xmlContent = fs.readFileSync(siteTemplateXmlPath, "utf8")
+    const parser = new XMLParser({
+      ignoreAttributes: true,
+      trimValues: true,
+      parseTagValue: false,
+      parseAttributeValue: false,
+    })
+    const parsed = parser.parse(xmlContent) as unknown
+    const customCartridges = findCustomCartridges(parsed)
+
+    if (!customCartridges) {
+      return []
+    }
+
+    return customCartridges
+      .split(":")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0)
+  } catch {
+    return []
+  }
+}

src/plugins/_utils/site-template-cartridge-path.ts

@@ -4,6 +4,7 @@ import fs from "node:fs"
 import path from "node:path"
 
 import { withSfccSettings } from "../_utils/sfcc-settings.js"
+import { getSiteTemplateCartridgePath } from "../_utils/site-template-cartridge-path.js"
 
 const SUPPORTED_EXTENSIONS = ["js", "ds", "json"]
 
@@ -101,17 +102,15 @@ function starReferenceExists(
   requirePath: string,
   cartridgesDir: string,
   cwd: string,
-  configuredCartridgePath: string[],
+  cartridgePath: string[],
 ): boolean {
   const moduleTarget = requirePath.slice(2)
   if (!moduleTarget) {
     return false
   }
 
   const cartridgeNames =
-    configuredCartridgePath.length > 0
-      ? configuredCartridgePath
-      : getFilesystemCartridges(cartridgesDir, cwd)
+    cartridgePath.length > 0 ? cartridgePath : getFilesystemCartridges(cartridgesDir, cwd)
 
   return cartridgeNames.some((name) =>
     moduleExistsInCartridge(name, moduleTarget, cartridgesDir, cwd),
@@ -173,11 +172,18 @@ const validRequirePath: Rule.RuleModule = {
     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 configuredCartridgePath = getConfiguredCartridgePath(options.cartridgePath)
+    const templateCartridgePath = getSiteTemplateCartridgePath(
+      options.siteTemplatePath,
+      options.site,
+      cwd,
+    )
+    const cartridgePath =
+      configuredCartridgePath.length > 0 ? configuredCartridgePath : templateCartridgePath
     const filename =
       (context as Rule.RuleContext & { filename?: string }).filename ??
       (context as Rule.RuleContext & { getFilename?: () => string }).getFilename?.() ??
@@ -207,7 +213,7 @@ const validRequirePath: Rule.RuleModule = {
         if (requirePath.startsWith("*/")) {
           if (
             checkCartridgeExists &&
-            !starReferenceExists(requirePath, cartridgesDir, cwd, configuredCartridgePath)
+            !starReferenceExists(requirePath, cartridgesDir, cwd, cartridgePath)
           ) {
             context.report({
               node: firstArgument,

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

@@ -3,4 +3,6 @@ export interface SfccSettings {
   checkCartridgeExists?: boolean
   cartridgesDir?: string
   cartridgePath?: string[]
+  siteTemplatePath?: string
+  site?: string
 }

src/types/sfcc-settings.ts

@@ -127,6 +127,57 @@ test("supports checkCartridgeExists option", () => {
   expect(hits.some((m) => m.message.includes("~/cartridge/scripts/does-not-exist"))).toBe(true)
 })
 
+test("supports cartridge order from site template", () => {
+  const testSuffix = `${Date.now()}_${Math.floor(Math.random() * 1_000_000)}`
+  const cartridgeName = `app_storefront_${testSuffix}`
+  const ownCartridgeName = `app_sfra_${testSuffix}`
+  const cartridgesDir = path.join(process.cwd(), "cartridges")
+  const targetCartridge = path.join(cartridgesDir, cartridgeName)
+  const ownCartridge = path.join(cartridgesDir, ownCartridgeName)
+  const siteTemplatePath = path.join(process.cwd(), `site_template_${testSuffix}`)
+  const site = "example"
+  const siteTemplateXmlPath = path.join(siteTemplatePath, "sites", site, "site.xml")
+
+  fs.mkdirSync(path.join(targetCartridge, "cartridge", "scripts"), { recursive: true })
+  fs.mkdirSync(path.join(ownCartridge, "cartridge", "scripts"), { recursive: true })
+  fs.mkdirSync(path.dirname(siteTemplateXmlPath), { recursive: true })
+  fs.writeFileSync(
+    path.join(targetCartridge, "cartridge", "scripts", "ok.js"),
+    "module.exports = true",
+  )
+  try {
+    fs.writeFileSync(
+      siteTemplateXmlPath,
+      `<site><custom-cartridges>app_base:${cartridgeName}:int_payments</custom-cartridges></site>`,
+    )
+
+    const linter = new Linter()
+    const config = createRecommendedConfig({
+      cartridgesDir: "cartridges",
+      sfcc: {
+        checkCartridgeExists: true,
+        siteTemplatePath,
+        site,
+      },
+    })
+
+    const messages = linter.verify(
+      `
+        const okStar = require("*/cartridge/scripts/ok")
+        module.exports = { okStar }
+      `,
+      config,
+      { filename: `cartridges/${ownCartridgeName}/cartridge/controllers/Home.js` },
+    )
+
+    expect(messages.some((m) => m.ruleId === "sfcc/valid-require-path")).toBe(false)
+  } finally {
+    fs.rmSync(targetCartridge, { recursive: true, force: true })
+    fs.rmSync(ownCartridge, { recursive: true, force: true })
+    fs.rmSync(siteTemplatePath, { recursive: true, force: true })
+  }
+})
+
 test("rejects direct rule options and requires shared settings", () => {
   const linter = new Linter()