@fjall/eslint-plugin 2.18.1

package/no-zod-enum-redeclaring-named-constant.js

@@ -0,0 +1,159 @@
+/**
+ * ESLint Rule: no-zod-enum-redeclaring-named-constant
+ *
+ * Catches `z.enum([<string-literal>, ...])` declarations whose literal set
+ * matches any named SCREAMING_SNAKE_CASE `as const` tuple in
+ * `generator/src/schemas/constants.ts` or `sharedTypes.ts` — covers the
+ * `_TYPES`, `_TIERS`, `_PRESETS`, `_PROVIDERS`, `_ENGINES`, `_METHODS`,
+ * `_NAMES`, `_INTERVALS`, `_ARCHITECTURES`, `_VALUES` suffix families. Any
+ * exported tuple matching `/^[A-Z][A-Z0-9_]*$/` participates; suffix is not
+ * gated. Set equality is ordering-insensitive — a `z.enum(["AWS_IAM","NONE"])`
+ * site matches `FUNCTION_URL_AUTH_TYPES = ["NONE","AWS_IAM"]`.
+ *
+ * Surfaces during the 2026-05-07 review pass as the 4th recurrence of
+ * literal-set drift on a Zod enum within one branch (F4 architecture · F9
+ * functionUrl.authType · F14 BACKUP_VAULT_TIERS test · F17 deployment).
+ * The 14:42 deltas note pre-registered the threshold; this rule mechanises it.
+ *
+ * Why ordering-insensitive set equality is correct: divergent orderings
+ * between sibling sites (e.g. `z.enum(["NONE","AWS_IAM"])` at one schema
+ * arm and `z.enum(["AWS_IAM","NONE"])` at another) are themselves a
+ * silent-drift hazard — both should route through the named tuple.
+ *
+ * The registry is built dynamically at rule-init time by reading
+ * `constants.ts` + `sharedTypes.ts` relative to this rule file. Adding a
+ * new `<NAME> = [...] as const` tuple (any SCREAMING_SNAKE_CASE name) to
+ * either source file automatically extends the rule's catch surface — no
+ * rule edits needed. Spread/concat forms (`APP_TYPES = [...TIER_NAMES, X]`)
+ * are intentionally not extracted — they would yield partial literal sets.
+ *
+ * Codifies typescript-standards.md § "Zod-Derived Type Guards (MANDATORY)".
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const REGISTRY = buildRegistry();
+
+function buildRegistry() {
+  const sources = [
+    join(__dirname, "..", "..", "generator", "src", "schemas", "constants.ts"),
+    join(__dirname, "..", "..", "generator", "src", "schemas", "sharedTypes.ts")
+  ];
+  const registry = new Map();
+  const failures = [];
+  for (const path of sources) {
+    let text;
+    try {
+      text = readFileSync(path, "utf8");
+    } catch (err) {
+      failures.push({
+        path,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      continue;
+    }
+    extractNamedTuples(text, registry);
+  }
+  if (registry.size === 0 && failures.length > 0) {
+    const detail = failures.map((f) => `${f.path}: ${f.error}`).join("; ");
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[fjall/no-zod-enum-redeclaring-named-constant] registry empty; rule disabled. ${detail}`
+    );
+  }
+  return registry;
+}
+
+function extractNamedTuples(source, registry) {
+  // Spread/concat forms like `APP_TYPES = [...TIER_NAMES, CUSTOM_TIER]` are
+  // intentionally not matched — they would yield partial literal sets.
+  const tuplePattern =
+    /export\s+const\s+([A-Z][A-Z0-9_]*)\s*=\s*\[\s*((?:"[^"]*"\s*,?\s*)+)\]\s*as\s+const/g;
+  let match;
+  while ((match = tuplePattern.exec(source)) !== null) {
+    const name = match[1];
+    const body = match[2];
+    const literals = Array.from(body.matchAll(/"([^"]*)"/g)).map((m) => m[1]);
+    if (literals.length === 0) continue;
+    const key = canonicalKey(literals);
+    if (!registry.has(key)) {
+      registry.set(key, name);
+    }
+  }
+}
+
+function canonicalKey(literals) {
+  return JSON.stringify([...literals].sort());
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow inline z.enum([...]) declarations whose literal set matches a named *_TYPES tuple",
+      category: "Best Practices",
+      recommended: true
+    },
+    messages: {
+      enumRedeclaresNamedConstant:
+        "z.enum([{{literals}}]) inline-redeclares the named constant `{{constantName}}` (literal set matches, ordering-insensitive). Replace with `z.enum({{constantName}})` to eliminate silent-drift risk."
+    },
+    schema: []
+  },
+
+  create(context) {
+    if (REGISTRY.size === 0) return {};
+
+    return {
+      CallExpression(node) {
+        if (!isZodEnumCall(node)) return;
+        const args = node.arguments;
+        if (args.length !== 1) return;
+        const arg = args[0];
+        if (arg.type !== "ArrayExpression") return;
+
+        const literals = [];
+        for (const element of arg.elements) {
+          if (
+            element === null ||
+            element.type !== "Literal" ||
+            typeof element.value !== "string"
+          ) {
+            return;
+          }
+          literals.push(element.value);
+        }
+        if (literals.length === 0) return;
+
+        const key = canonicalKey(literals);
+        const constantName = REGISTRY.get(key);
+        if (constantName === undefined) return;
+
+        context.report({
+          node: arg,
+          messageId: "enumRedeclaresNamedConstant",
+          data: {
+            literals: literals.map((l) => `"${l}"`).join(", "),
+            constantName
+          }
+        });
+      }
+    };
+  }
+};
+
+function isZodEnumCall(node) {
+  if (node.type !== "CallExpression") return false;
+  const callee = node.callee;
+  if (callee.type !== "MemberExpression") return false;
+  if (callee.property.type !== "Identifier") return false;
+  if (callee.property.name !== "enum") return false;
+  if (callee.object.type !== "Identifier") return false;
+  return callee.object.name === "z";
+}

package/no-zod-optional-string-empty-trap.js

@@ -0,0 +1,193 @@
+/**
+ * ESLint Rule: no-zod-optional-string-empty-trap
+ *
+ * Flags `z.string()...optional()` (or `.nullable()`) chains without `.min(N)`
+ * whose corresponding destructured field name is consumed by `??` in the same
+ * file. The empty string passes Zod's `.optional()` (only "absent" is rejected,
+ * not `""`), but `??` only falls through on null/undefined — so `""` flows past
+ * the fallback and lands in downstream consumers as an empty string.
+ *
+ * Per .claude/rules/typescript-standards.md § "Pitfall 9: `.optional()` String
+ * Composed With `??` Fallback (Empty-String Trap)".
+ *
+ * Detection algorithm (heuristic, file-scoped):
+ *   Pass 1 — collect Property nodes whose value is `z.string()...optional()` or
+ *            `.nullable()` chains lacking `.min(N)`. Index by field name.
+ *   Pass 2 — collect `??` LogicalExpressions whose LHS is `Identifier(name)` or
+ *            `MemberExpression(.name)`.
+ *   Report  — at Program:exit, intersect by name. Each vulnerable field is
+ *            reported once even if consumed by multiple `??` operators.
+ *
+ * Rename-aware:
+ *   `const { region: requestedRegion } = data; requestedRegion ?? "x"` is
+ *   matched by walking ObjectPattern Property nodes (key.name → value.name)
+ *   and looking up `??` LHS bindings against the rename map when a direct
+ *   schema-property-name match fails.
+ *
+ * Heuristic limitations:
+ *   - Cross-file flow not tracked. Schemas declared in one file and consumed
+ *     in another are out of scope.
+ *   - Multi-step rebinding (`const x = data.field; const y = x; y ?? "z"`) is
+ *     not traced — only single-step destructuring renames are tracked.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow z.string()...optional() (or .nullable()) without .min(N) when the destructured field flows into a `??` consumer.",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      emptyStringTrap:
+        'Field `{{name}}` is `z.string()...{{absentMethod}}()` without `.min(N)` and is consumed by `??` (line {{consumerLine}}). Empty-string body bypasses the fallback. Add `.min(1, "{{name}} cannot be empty")` before `.{{absentMethod}}()`, or document why empty string is valid here with an eslint-disable.'
+    },
+    schema: []
+  },
+
+  create(context) {
+    /** @type {Map<string, { propertyNode: any, absentMethod: string }>} */
+    const vulnerableFields = new Map();
+    /** @type {Array<{ node: any, name: string }>} */
+    const consumers = [];
+    /** @type {Map<string, string>} localBindingName -> originalSchemaPropertyName */
+    const renameMap = new Map();
+
+    return {
+      Property(node) {
+        if (node.key.type !== "Identifier") return;
+
+        if (node.parent && node.parent.type === "ObjectPattern") {
+          if (
+            !node.shorthand &&
+            node.value.type === "Identifier" &&
+            node.key.name !== node.value.name
+          ) {
+            renameMap.set(node.value.name, node.key.name);
+          }
+          return;
+        }
+
+        const fieldName = node.key.name;
+        const result = analyseZodChain(node.value);
+        if (result.isAbsentAcceptingString && !result.hasMin) {
+          vulnerableFields.set(fieldName, {
+            propertyNode: node,
+            absentMethod: result.absentMethod
+          });
+        }
+      },
+
+      "LogicalExpression[operator='??']"(node) {
+        const name = extractIdentifierName(node.left);
+        if (name) consumers.push({ node, name });
+      },
+
+      "Program:exit"() {
+        const reported = new Set();
+        for (const { node, name } of consumers) {
+          let schemaName = name;
+          let entry = vulnerableFields.get(schemaName);
+          if (!entry) {
+            const renamedFrom = renameMap.get(name);
+            if (renamedFrom) {
+              schemaName = renamedFrom;
+              entry = vulnerableFields.get(schemaName);
+            }
+          }
+          if (!entry || reported.has(schemaName)) continue;
+          reported.add(schemaName);
+          context.report({
+            node: entry.propertyNode,
+            messageId: "emptyStringTrap",
+            data: {
+              name: schemaName,
+              absentMethod: entry.absentMethod,
+              consumerLine: String(node.loc.start.line)
+            }
+          });
+        }
+      }
+    };
+  }
+};
+
+/**
+ * Walks a Zod chain (the value of a Property in a z.object literal) and
+ * determines whether it forms `z.string()...optional()` or `.nullable()`
+ * without `.min(N)`. Returns the absent-accepting method name so the report
+ * can target it precisely.
+ */
+function analyseZodChain(node) {
+  let baseIsString = false;
+  /** @type {string[]} */
+  const methodCalls = [];
+  let hasProtectiveMin = false;
+
+  let current = node;
+  while (current && current.type === "CallExpression") {
+    const callee = current.callee;
+    if (
+      callee.type !== "MemberExpression" ||
+      callee.property.type !== "Identifier"
+    ) {
+      break;
+    }
+    const methodName = callee.property.name;
+
+    if (
+      callee.object.type === "Identifier" &&
+      callee.object.name === "z" &&
+      methodName === "string"
+    ) {
+      baseIsString = true;
+      break;
+    }
+
+    if (methodName === "min" && isProtectiveMinCall(current)) {
+      hasProtectiveMin = true;
+    }
+
+    methodCalls.push(methodName);
+    current = callee.object;
+  }
+
+  let absentMethod = null;
+  if (methodCalls.includes("optional")) absentMethod = "optional";
+  else if (methodCalls.includes("nullable")) absentMethod = "nullable";
+
+  return {
+    isAbsentAcceptingString: baseIsString && absentMethod !== null,
+    hasMin: hasProtectiveMin,
+    absentMethod
+  };
+}
+
+/**
+ * `.min(N)` only protects against the empty-string trap when `N >= 1`.
+ * `.min(0)` accepts `""` so the trap stays open. Treat non-literal arguments
+ * (`.min(MIN_LEN)`) as protective — flagging known-good shapes is worse than
+ * missing edge-case literals.
+ */
+function isProtectiveMinCall(callExpression) {
+  const arg = callExpression.arguments?.[0];
+  if (!arg) return false;
+  if (arg.type !== "Literal") return true;
+  return typeof arg.value === "number" && arg.value >= 1;
+}
+
+/**
+ * Returns the rightmost identifier name when node is `Identifier` or
+ * `MemberExpression` (so both `field ?? x` and `parsed.field ?? x` match).
+ */
+function extractIdentifierName(node) {
+  if (!node) return null;
+  if (node.type === "Identifier") return node.name;
+  if (node.type === "MemberExpression" && node.property.type === "Identifier") {
+    return node.property.name;
+  }
+  return null;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@fjall/eslint-plugin",
+  "version": "2.18.1",
+  "description": "ESLint plugin with Fjall-specific coding standard rules",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "fjall"
+  ],
+  "scripts": {
+    "clean": "rm -rf ./dist ./sourcemaps",
+    "clean:node": "rm -rf ./node_modules",
+    "build": "echo \"@fjall/eslint-plugin: no build step (plain JS, published as source)\"",
+    "watch": "echo \"@fjall/eslint-plugin: no watch (no build step)\"",
+    "format": "prettier --write \"*.js\" \"__tests__/**/*.js\" README.md",
+    "format:check": "prettier --check \"*.js\" \"__tests__/**/*.js\" README.md"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}

package/paired-ecs-validation.js

@@ -0,0 +1,208 @@
+/**
+ * ESLint Rule: paired-ecs-validation
+ *
+ * Enforces the resources-vs-patterns layered validation discipline codified in
+ * `.claude/rules/generator-standards.md § "Validate at the Lowest Layer the
+ * Field Belongs To"`. When the patterns-layer hook (`validateEcsProps` in
+ * `lib/patterns/aws/computeEcs.ts`) checks a field on `service.X` or
+ * `service.deployment.X`, the same field MUST be referenced in the
+ * resources-layer hook (`validateEcsClusterProps` in
+ * `lib/resources/aws/compute/ecsValidation.ts`) — otherwise direct
+ * `new EcsCluster(...)` consumers bypass the check entirely.
+ *
+ * The 2026-05-10 ClickHouse review found `service.deployment.{min,max}HealthyPercent`
+ * and `service.cloudMapDnsRecordType` validated only in `validateEcsProps`. Six
+ * call sites in `lib/__tests__/ecs-loadbalancer-url.test.ts` plus the
+ * JSDoc-documented public-API shape bypassed every check. Same defect class
+ * as the 2026-05-07 F6 `directAccess` gap.
+ *
+ * This rule fires on the patterns-layer file. For each `service.<X>` (or
+ * `service.deployment.<X>`) member access inside `validateEcsProps`'s body,
+ * it verifies the same chain appears textually in the sibling
+ * resources-layer file. Cross-file read uses the synchronous fs API at
+ * rule-load time and is cached for the lifetime of the lint session.
+ *
+ * Detection limitations (acknowledged ceiling):
+ *   - Textual cross-file match. A patterns-layer `service.deployment.minHealthyPercent`
+ *     access requires the literal substring `deployment.minHealthyPercent` to
+ *     appear somewhere in `ecsValidation.ts`. Renames or destructured
+ *     references (`const { minHealthyPercent: min } = service.deployment`)
+ *     would defeat the textual match and require structural AST analysis.
+ *   - False-negatives via incidental substring. Because the check is a
+ *     `String.includes(...)`, an unrelated occurrence of `.deployment` or
+ *     `.<field>` in `ecsValidation.ts` (e.g. inside a comment, a JSDoc
+ *     example, a type alias name like `DeploymentConfig`) satisfies the
+ *     match without the actual field being validated. The rule trades
+ *     this slack for cross-file simplicity; the runtime-test discipline
+ *     in `code-quality.md § "ESLint-Mandated Validations Need Direct
+ *     Runtime Tests"` is the backstop.
+ *   - Only checks the patterns-layer → resources-layer direction. Resources
+ *     layer can validate fields the patterns layer does not (correct: the
+ *     resources layer is the lower mandatory layer; patterns is optional
+ *     defence-in-depth).
+ *   - Hardcoded for the `validateEcsProps` ↔ `validateEcsClusterProps` pair.
+ *     If a future layered API needs the same check, factor the pair list
+ *     into rule options.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const PATTERNS_LAYER_FILENAME_SUFFIX =
+  "components/infrastructure/lib/patterns/aws/computeEcs.ts";
+const RESOURCES_LAYER_RELATIVE_PATH =
+  "../../resources/aws/compute/ecsValidation.ts";
+const PATTERNS_LAYER_FUNCTION_NAME = "validateEcsProps";
+const RESOURCES_LAYER_FUNCTION_NAME = "validateEcsClusterProps";
+
+/** Cache the resources-layer file content per process — invalidated only on
+ *  ESLint restart. The lint session reads `ecsValidation.ts` once even if
+ *  `computeEcs.ts` is linted across many changes in a watch session.
+ *
+ *  Caveat: edits to `ecsValidation.ts` during a watch session are NOT picked
+ *  up until ESLint restarts. Reload `eslint --cache --fix .` or restart the
+ *  editor's ESLint server to refresh. The trade-off: per-lint disk reads
+ *  would add noticeable latency on every `computeEcs.ts` edit in monorepo
+ *  watch mode, whereas the rule's purpose is enforced at commit time via
+ *  lefthook's lint-staged hook regardless of watch-session staleness. */
+const resourcesFileCache = new Map();
+
+function readResourcesLayer(patternsFilePath) {
+  const resourcesPath = resolve(
+    dirname(patternsFilePath),
+    RESOURCES_LAYER_RELATIVE_PATH
+  );
+  if (resourcesFileCache.has(resourcesPath)) {
+    return resourcesFileCache.get(resourcesPath);
+  }
+  let content = "";
+  try {
+    content = readFileSync(resourcesPath, "utf8");
+  } catch (err) {
+    process.emitWarning(
+      `paired-ecs-validation: could not read sibling file ${resourcesPath} (${err && err.code ? err.code : "ENOENT"}); rule disabled for ${patternsFilePath}.`,
+      "ESLintRuleWarning"
+    );
+    content = "";
+  }
+  resourcesFileCache.set(resourcesPath, content);
+  return content;
+}
+
+/** Recursively flatten a chain like `service.deployment.minHealthyPercent`
+ *  into `["service", "deployment", "minHealthyPercent"]`. Returns null if any
+ *  link in the chain is computed (`service[x]`) or non-Identifier. */
+function flattenMemberChain(node) {
+  const chain = [];
+  let current = node;
+  while (current && current.type === "MemberExpression") {
+    if (current.computed) return null;
+    if (!current.property || current.property.type !== "Identifier") {
+      return null;
+    }
+    chain.unshift(current.property.name);
+    current = current.object;
+  }
+  if (!current || current.type !== "Identifier") return null;
+  chain.unshift(current.name);
+  return chain;
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Enforces that fields validated in the patterns-layer `validateEcsProps` hook are also validated in the resources-layer `validateEcsClusterProps` hook. Direct `new EcsCluster(...)` consumers bypass the patterns layer.",
+      category: "Best Practices",
+      recommended: true
+    },
+    messages: {
+      missingResourcesLayerCheck:
+        '`{{chain}}` is validated here in `validateEcsProps` (patterns layer) but the field is not referenced in `validateEcsClusterProps` (resources layer). Direct `new EcsCluster(...)` consumers bypass the patterns-layer check — add the same validation to `lib/resources/aws/compute/ecsValidation.ts` so both code paths are protected. See .claude/rules/generator-standards.md § "Validate at the Lowest Layer the Field Belongs To".'
+    },
+    schema: []
+  },
+
+  create(context) {
+    const filename = context.filename ?? context.getFilename();
+    if (!filename.endsWith(PATTERNS_LAYER_FILENAME_SUFFIX)) return {};
+
+    const resourcesContent = readResourcesLayer(filename);
+    if (resourcesContent === "") return {};
+
+    let insideTargetFunction = 0;
+    const reportedChains = new Set();
+
+    function enterIfTarget(node) {
+      if (node.id && node.id.name === PATTERNS_LAYER_FUNCTION_NAME) {
+        insideTargetFunction += 1;
+      }
+    }
+
+    function exitIfTarget(node) {
+      if (node.id && node.id.name === PATTERNS_LAYER_FUNCTION_NAME) {
+        insideTargetFunction -= 1;
+      }
+    }
+
+    return {
+      FunctionDeclaration: enterIfTarget,
+      "FunctionDeclaration:exit": exitIfTarget,
+      VariableDeclarator(node) {
+        if (
+          node.init &&
+          (node.init.type === "ArrowFunctionExpression" ||
+            node.init.type === "FunctionExpression")
+        ) {
+          enterIfTarget(node);
+        }
+      },
+      "VariableDeclarator:exit"(node) {
+        if (
+          node.init &&
+          (node.init.type === "ArrowFunctionExpression" ||
+            node.init.type === "FunctionExpression")
+        ) {
+          exitIfTarget(node);
+        }
+      },
+
+      MemberExpression(node) {
+        if (insideTargetFunction === 0) return;
+        const chain = flattenMemberChain(node);
+        if (!chain || chain.length < 2) return;
+        const root = chain[0];
+        if (root !== "service" && root !== "props") return;
+
+        const tail = chain.slice(1).join(".");
+        if (!tail) return;
+
+        const ancestorTails = [tail];
+        for (let i = chain.length - 1; i > 1; i -= 1) {
+          ancestorTails.push(chain.slice(1, i).join("."));
+        }
+
+        for (const candidate of ancestorTails) {
+          if (
+            resourcesContent.includes(`${root}.${candidate}`) ||
+            resourcesContent.includes(`.${candidate}`)
+          ) {
+            return;
+          }
+        }
+
+        const reportKey = `${root}.${tail}`;
+        if (reportedChains.has(reportKey)) return;
+        reportedChains.add(reportKey);
+
+        context.report({
+          node,
+          messageId: "missingResourcesLayerCheck",
+          data: { chain: `${root}.${tail}` }
+        });
+      }
+    };
+  }
+};

package/prefer-set-has.js

@@ -0,0 +1,84 @@
+/**
+ * ESLint Rule: prefer-set-has
+ *
+ * Prefer Set.has() over Array.includes() for SCREAMING_CASE lookup tables.
+ * - Set.has() is O(1), Array.includes() is O(n)
+ * - Only flags SCREAMING_CASE constants (e.g., ALLOWED_TYPES)
+ * - Does NOT flag camelCase variables (small arrays where O(n) is fine)
+ *
+ * Detects patterns like:
+ * - SOME_ARRAY.includes(value)
+ *
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Prefer Set.has() over Array.includes() for membership checks",
+      category: "Performance",
+      recommended: false
+    },
+    messages: {
+      preferSet:
+        "Use Set.has() instead of Array.includes() for O(1) lookup. Define {{name}} as 'new Set([...])' and replace `.includes(x)` with `.has(x)` at the call site."
+    },
+    schema: []
+  },
+
+  create(context) {
+    return {
+      // Detect .includes() calls on SCREAMING_CASE arrays (likely lookup tables)
+      CallExpression(node) {
+        if (!isIncludesCall(node)) return;
+
+        const callee = node.callee;
+        if (callee.type !== "MemberExpression") return;
+
+        const object = callee.object;
+
+        // Only check identifiers
+        if (object.type !== "Identifier") return;
+
+        const arrayName = object.name;
+
+        // Only report SCREAMING_CASE constants - these are clearly lookup tables
+        // Don't report camelCase variables as they may be small/dynamic arrays
+        // where the O(1) vs O(n) difference is negligible
+        if (isScreamingCase(arrayName)) {
+          context.report({
+            node,
+            messageId: "preferSet",
+            data: { name: arrayName }
+          });
+        }
+      }
+    };
+  }
+};
+
+/**
+ * Check if node is a .includes() call
+ */
+function isIncludesCall(node) {
+  if (node.type !== "CallExpression") return false;
+
+  const callee = node.callee;
+  if (callee.type !== "MemberExpression") return false;
+
+  return (
+    callee.property.type === "Identifier" && callee.property.name === "includes"
+  );
+}
+
+/**
+ * Check if name is SCREAMING_SNAKE_CASE (constant naming convention).
+ * Requires an underscore separator OR length >= 4 so single-letter generics
+ * (`T`, `X`) and short locals (`OK`, `ID`) aren't matched as lookup tables.
+ */
+function isScreamingCase(name) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(name)) return false;
+  return name.includes("_") || name.length >= 4;
+}