@fjall/eslint-plugin 2.18.1

package/no-tier-stage-conflation.js

@@ -0,0 +1,423 @@
+/**
+ * ESLint Rule: no-tier-stage-conflation
+ *
+ * `ConnectedAwsAccount` carries two INDEPENDENT axes:
+ *   - `role`        = structural TIER  (organisation | platform | account)
+ *   - `environment` = workload STAGE   (production | staging | development |
+ *                                       platform | compliance, nullable)
+ *
+ * "platform" is BOTH a tier and a stage — same name, two independent axes.
+ * Only "root" is excluded from the stage vocabulary.
+ *
+ * A lossy bridge once derived one axis from the other — `environmentToRole()`
+ * on every write, plus a `role === 'organisation' ? null : environment` wipe,
+ * plus a name-fallback that mis-derived the tier of an account literally
+ * named "platform"/"root". Selecting a "stage" of platform silently flipped
+ * the tier; a worker re-syncing a stage demoted a root. Phase 3 (2026-06-07
+ * tier/stage separation) deleted those derivations. This rule stops them
+ * coming back.
+ *
+ * Detects three AST shapes (ADR
+ * decisions/2026-06-07-account-tier-vs-stage-separation.md § "Regression
+ * prevention" item 1):
+ *
+ *   A. The structural "root" marker admitted into a picker-shaped array — a
+ *      string literal "root" (or an environment-constant `.ROOT` member such
+ *      as `STRUCTURAL_ENVIRONMENTS.ROOT`) inside an ArrayExpression bound to
+ *      a name matching /(_STAGES|_OPTIONS|_CHOICES)$/i, including the
+ *      spread-recomposition form `[...ACCOUNT_STAGES, "root"]`. "root" is the
+ *      TIER wire marker (decodes to role=organisation), never a workload
+ *      STAGE — pickers must not offer it. NB: "platform" IS a legitimate
+ *      stage and is allowed in stage arrays.
+ *
+ *   B. `role: <call(...environment...)>` where the callee is NOT a sanctioned
+ *      wire decoder — deriving the TIER from the STAGE on a write path; plus
+ *      `environment: <role === 'organisation' ? ... : ...>` — forcing/wiping
+ *      the STAGE based on the TIER.
+ *
+ *   C. Tier-from-name derivation — a `role:`/`tier:` property or variable
+ *      whose value compares (or regex-tests) an account NAME member
+ *      (`account.name`, `acc.Name`, `account.displayName`, ...) against
+ *      organisation | platform | root | management. ADR symptom 3: the
+ *      deleted name-fallback bridge corrupted the tier of an account whose
+ *      display name happened to be "platform"/"root" — the name is
+ *      independent of both axes.
+ *
+ * Shape A exemptions (false-positive bias is deliberately LOW):
+ *   - Names containing WITH_ROOT: the canonical wire supersets in
+ *     fjall/util/src/environments.ts (`ACCOUNT_STAGES_WITH_ROOT`) deliberately
+ *     admit "root" for superset-tolerant ingress and say so in their name.
+ *   - Names matching /WIRE|LEGACY/: wire-tolerance tuples for out-of-version
+ *     CLI ingest are sanctioned by the ADR ("Wire tuples exempt from shape A").
+ *   - `.ROOT` members only count when the object name references the
+ *     environment vocabulary (/ENVIRONMENT|STAGE/i) — `ROUTES.ROOT` in a nav
+ *     options array is not the structural marker.
+ *   - Test files are excluded at registration (both eslint.config.mjs
+ *     registrations carry test-glob ignores).
+ *
+ * Shape C is conservative: it only fires when the comparison demonstrably
+ * feeds a role/tier binding (a `role:`/`tier:` property, a variable named
+ * `role`/`tier`, or an assignment to `.role`/`.tier`), and does not descend
+ * into nested function bodies (a `.find((r) => r.name === ...)` predicate is
+ * a lookup, not a derivation).
+ *
+ * The sanctioned one-directional wire decoders (`environmentToTier`,
+ * `accountTier`) are exempt from shape B by name: decoding the
+ * root/platform-tolerant wire `environment` into a tier at ingress is the
+ * correct replacement. A novel re-derivation — for any shape — requires an
+ * explicit `eslint-disable-next-line fjall/no-tier-stage-conflation --
+ * <reason>` so the exception is visible in review.
+ */
+
+const SANCTIONED_TIER_DECODERS = new Set(["environmentToTier", "accountTier"]);
+const STRUCTURAL_ROLE_LITERALS = new Set(["organisation", "platform"]);
+
+const PICKER_ARRAY_NAME = /(_STAGES|_OPTIONS|_CHOICES)$/i;
+const WIRE_TOLERANT_ARRAY_NAME = /WITH_ROOT|WIRE|LEGACY/i;
+const ENVIRONMENT_CONSTANT_OBJECT = /ENVIRONMENT|STAGE/i;
+
+const TIER_BINDING_NAME = /^(role|tier)$/;
+const NAME_MEMBER_PROPERTY = /name/i;
+const TIER_NAME_LITERALS = new Set([
+  "organisation",
+  "platform",
+  "root",
+  "management"
+]);
+const TIER_NAME_REGEX_WORD = /\b(organisation|platform|root|management)\b/i;
+const EQUALITY_OPERATORS = new Set(["===", "!==", "==", "!="]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow conflating the ConnectedAwsAccount TIER (role) and STAGE (environment) axes: no structural 'root' in picker arrays, no tier derived from the stage (or vice versa) on a write path, and no tier derived from an account name. Suppress intentional exceptions with `eslint-disable-next-line fjall/no-tier-stage-conflation -- <reason>`.",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      roleFromEnvironment:
+        "Do not derive `role` (TIER) from `environment` (STAGE): `{{callee}}(…)` conflates the two axes. Decode the wire value with the sanctioned `environmentToTier` / `accountTier`, or write an explicit role.",
+      environmentWipedByRole:
+        "Do not force/wipe `environment` (STAGE) from `role === '{{tier}}'` (TIER): the axes are independent. Write the decoded stage (`stageFromWireEnvironment`) instead of a role-keyed ternary.",
+      structuralRootInPickerArray:
+        "Do not admit the structural 'root' marker into the picker-shaped array `{{name}}`: 'root' is the TIER wire marker (decodes to role=organisation), never a workload STAGE. Use ACCOUNT_STAGES, or import the canonical wire superset ACCOUNT_STAGES_WITH_ROOT from @fjall/util for wire-tolerant ingress schemas. Intentional exceptions need `eslint-disable-next-line fjall/no-tier-stage-conflation -- <reason>`.",
+      tierFromAccountName:
+        "Do not derive `{{binding}}` (TIER) from an account NAME comparison ({{comparator}}): the name is independent of both axes — an account literally named 'root'/'platform' must keep its tier. Decode the wire environment via `environmentToTier`/`accountTier`, or write the tier explicitly. Intentional exceptions need `eslint-disable-next-line fjall/no-tier-stage-conflation -- <reason>`."
+    },
+    schema: []
+  },
+
+  create(context) {
+    return {
+      Property(node) {
+        const keyName = propertyKeyName(node);
+        if (keyName === null) return;
+        if (keyName === "role") {
+          const offending = findUnsanctionedEnvCall(node.value);
+          if (offending) {
+            context.report({
+              node: node.value,
+              messageId: "roleFromEnvironment",
+              data: { callee: offending }
+            });
+          }
+        } else if (keyName === "environment") {
+          const tier = roleKeyedStructuralTernary(node.value);
+          if (tier) {
+            context.report({
+              node: node.value,
+              messageId: "environmentWipedByRole",
+              data: { tier }
+            });
+          }
+        }
+        if (TIER_BINDING_NAME.test(keyName)) {
+          reportTierFromName(context, keyName, node.value);
+        }
+        checkPickerArray(context, keyName, node.value);
+      },
+
+      VariableDeclarator(node) {
+        if (node.id.type !== "Identifier" || !node.init) return;
+        checkPickerArray(context, node.id.name, node.init);
+        if (TIER_BINDING_NAME.test(node.id.name)) {
+          reportTierFromName(context, node.id.name, node.init);
+        }
+      },
+
+      AssignmentExpression(node) {
+        const targetName = assignmentTargetName(node.left);
+        if (targetName === null) return;
+        checkPickerArray(context, targetName, node.right);
+        if (TIER_BINDING_NAME.test(targetName)) {
+          reportTierFromName(context, targetName, node.right);
+        }
+      }
+    };
+  }
+};
+
+function propertyKeyName(node) {
+  if (!node.key) return null;
+  if (node.key.type === "Identifier") return node.key.name;
+  if (node.key.type === "Literal" && typeof node.key.value === "string") {
+    return node.key.value;
+  }
+  return null;
+}
+
+function assignmentTargetName(left) {
+  if (left.type === "Identifier") return left.name;
+  if (
+    left.type === "MemberExpression" &&
+    !left.computed &&
+    left.property.type === "Identifier"
+  ) {
+    return left.property.name;
+  }
+  return null;
+}
+
+function calleeName(callee) {
+  if (callee.type === "Identifier") return callee.name;
+  if (
+    callee.type === "MemberExpression" &&
+    callee.property.type === "Identifier"
+  ) {
+    return callee.property.name;
+  }
+  return null;
+}
+
+function referencesEnvironment(node) {
+  let found = false;
+  walk(node, (n) => {
+    if (n.type === "Identifier" && n.name === "environment") found = true;
+    if (
+      n.type === "MemberExpression" &&
+      n.property.type === "Identifier" &&
+      n.property.name === "environment"
+    ) {
+      found = true;
+    }
+  });
+  return found;
+}
+
+// Returns the offending callee name, or null. Recurses through ternary/logical
+// wrappers so `tier ?? environmentToRole(environment)` is caught while
+// `tier ?? environmentToTier(environment)` (sanctioned) is not.
+function findUnsanctionedEnvCall(node) {
+  let offending = null;
+  walk(node, (n) => {
+    if (offending) return;
+    if (n.type === "CallExpression") {
+      const name = calleeName(n.callee);
+      if (
+        name &&
+        !SANCTIONED_TIER_DECODERS.has(name) &&
+        n.arguments.some((arg) => referencesEnvironment(arg))
+      ) {
+        offending = name;
+      }
+    }
+  });
+  return offending;
+}
+
+function roleKeyedStructuralTernary(node) {
+  if (!node || node.type !== "ConditionalExpression") return null;
+  const test = node.test;
+  if (!test || test.type !== "BinaryExpression") return null;
+  if (test.operator !== "===" && test.operator !== "!==") return null;
+
+  const refsRole = (side) =>
+    (side.type === "Identifier" && side.name === "role") ||
+    (side.type === "MemberExpression" &&
+      side.property.type === "Identifier" &&
+      side.property.name === "role");
+
+  const structuralLiteral = (side) => {
+    if (side.type === "Literal" && typeof side.value === "string") {
+      return STRUCTURAL_ROLE_LITERALS.has(side.value) ? side.value : null;
+    }
+    if (
+      side.type === "MemberExpression" &&
+      side.property.type === "Identifier"
+    ) {
+      const name = side.property.name.toLowerCase();
+      return STRUCTURAL_ROLE_LITERALS.has(name) ? name : null;
+    }
+    return null;
+  };
+
+  if (refsRole(test.left)) return structuralLiteral(test.right);
+  if (refsRole(test.right)) return structuralLiteral(test.left);
+  return null;
+}
+
+// --- Shape A: structural "root" in a picker-shaped array -------------------
+
+function checkPickerArray(context, name, valueNode) {
+  if (!PICKER_ARRAY_NAME.test(name)) return;
+  // WITH_ROOT names (canonical wire supersets) and WIRE/LEGACY tuples
+  // deliberately admit "root" — see the header rationale.
+  if (WIRE_TOLERANT_ARRAY_NAME.test(name)) return;
+  const arrayNode = unwrapTsExpressions(valueNode);
+  if (!arrayNode || arrayNode.type !== "ArrayExpression") return;
+  for (const element of arrayNode.elements) {
+    if (!element || element.type === "SpreadElement") continue;
+    const unwrapped = unwrapTsExpressions(element);
+    if (isStructuralRootElement(unwrapped)) {
+      context.report({
+        node: unwrapped,
+        messageId: "structuralRootInPickerArray",
+        data: { name }
+      });
+    }
+  }
+}
+
+function isStructuralRootElement(node) {
+  if (!node) return false;
+  if (node.type === "Literal" && node.value === "root") return true;
+  // `.ROOT` member access counts only when the object is an
+  // environment-vocabulary constant (STRUCTURAL_ENVIRONMENTS.ROOT) — a
+  // `ROUTES.ROOT` nav entry is unrelated to the tier/stage axes.
+  return (
+    node.type === "MemberExpression" &&
+    !node.computed &&
+    node.property.type === "Identifier" &&
+    node.property.name === "ROOT" &&
+    node.object.type === "Identifier" &&
+    ENVIRONMENT_CONSTANT_OBJECT.test(node.object.name)
+  );
+}
+
+// --- Shape C: tier derived from an account NAME ----------------------------
+
+function reportTierFromName(context, bindingName, valueNode) {
+  const match = findTierFromNameComparison(valueNode);
+  if (match) {
+    context.report({
+      node: match.node,
+      messageId: "tierFromAccountName",
+      data: { binding: bindingName, comparator: match.comparator }
+    });
+  }
+}
+
+// Returns the offending comparison/regex-test, or null. Recurses through
+// ternary/?? wrappers (same piercing as shape B) but NOT into nested function
+// bodies — a comparison inside a callback is a lookup predicate, not the
+// value of the role/tier binding.
+function findTierFromNameComparison(node) {
+  let match = null;
+  walk(
+    node,
+    (n) => {
+      if (match) return;
+      if (n.type === "BinaryExpression" && EQUALITY_OPERATORS.has(n.operator)) {
+        const operandPairs = [
+          [n.left, n.right],
+          [n.right, n.left]
+        ];
+        for (const [memberSide, literalSide] of operandPairs) {
+          if (isNameMember(memberSide) && isTierNameLiteral(literalSide)) {
+            match = { node: n, comparator: `'${literalSide.value}'` };
+            return;
+          }
+        }
+      }
+      if (
+        n.type === "CallExpression" &&
+        n.callee.type === "MemberExpression" &&
+        !n.callee.computed &&
+        n.callee.property.type === "Identifier"
+      ) {
+        const method = n.callee.property.name;
+        if (
+          method === "test" &&
+          isTierNameRegex(n.callee.object) &&
+          n.arguments.some(isNameMember)
+        ) {
+          match = { node: n, comparator: `/${n.callee.object.regex.pattern}/` };
+        } else if (method === "match" && isNameMember(n.callee.object)) {
+          const regexArg = n.arguments.find(isTierNameRegex);
+          if (regexArg) {
+            match = { node: n, comparator: `/${regexArg.regex.pattern}/` };
+          }
+        }
+      }
+    },
+    { intoFunctions: false }
+  );
+  return match;
+}
+
+function isNameMember(node) {
+  return (
+    node.type === "MemberExpression" &&
+    !node.computed &&
+    node.property.type === "Identifier" &&
+    NAME_MEMBER_PROPERTY.test(node.property.name)
+  );
+}
+
+function isTierNameLiteral(node) {
+  return (
+    node.type === "Literal" &&
+    typeof node.value === "string" &&
+    TIER_NAME_LITERALS.has(node.value.toLowerCase())
+  );
+}
+
+function isTierNameRegex(node) {
+  return (
+    node.type === "Literal" &&
+    Boolean(node.regex) &&
+    TIER_NAME_REGEX_WORD.test(node.regex.pattern)
+  );
+}
+
+// --- Shared helpers ---------------------------------------------------------
+
+const TS_WRAPPER_TYPES = new Set([
+  "TSAsExpression",
+  "TSSatisfiesExpression",
+  "TSTypeAssertion",
+  "TSNonNullExpression"
+]);
+
+function unwrapTsExpressions(node) {
+  let current = node;
+  while (current && TS_WRAPPER_TYPES.has(current.type)) {
+    current = current.expression;
+  }
+  return current;
+}
+
+const FUNCTION_NODE_TYPES = new Set([
+  "FunctionDeclaration",
+  "FunctionExpression",
+  "ArrowFunctionExpression"
+]);
+
+// Minimal recursive AST walker over node-shaped own properties.
+function walk(node, visit, { intoFunctions = true } = {}) {
+  if (!node || typeof node.type !== "string") return;
+  visit(node);
+  if (!intoFunctions && FUNCTION_NODE_TYPES.has(node.type)) return;
+  for (const key of Object.keys(node)) {
+    if (key === "parent") continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const item of child) walk(item, visit, { intoFunctions });
+    } else if (child && typeof child.type === "string") {
+      walk(child, visit, { intoFunctions });
+    }
+  }
+}

package/no-undefined-prop-in-construct-id.js

@@ -0,0 +1,119 @@
+/**
+ * ESLint Rule: no-undefined-prop-in-construct-id
+ *
+ * Flags template-literal CDK construct IDs that interpolate `props.<X>` where
+ * `props` is a function parameter and `<X>` is an optionally-typed field on
+ * that parameter's type. When the caller passes `undefined`, the literal
+ * string `"undefined"` is baked into the CloudFormation logical ID — silent
+ * at synth time, audit-visible at runtime, drifts across deploys depending
+ * on caller choice.
+ *
+ * The M-9 class from the 2026-05-17 /review on the database factory variant
+ * narrowing landing — `rdsInstance.ts` + `rdsAurora.ts` carried 23 sites of
+ * shape `new Foo(this, \`${props.databaseName}Suffix\`, ...)` where
+ * `RdsProps.databaseName` is `string | undefined`. Constructor populated
+ * `this.databaseNameValue` with a fallback, so the canonical fix was to
+ * route every template-literal site through the class field.
+ *
+ * Detection (AST-only, no type info):
+ *   - File matches `lib/{resources,patterns,config}/aws/**\/*.ts` (via the
+ *     `files:` glob at the registration site in `fjall/eslint.config.mjs`).
+ *   - NewExpression's 2nd argument is a TemplateLiteral.
+ *   - The template literal contains an expression of shape `props.<X>`
+ *     (or any function-parameter name whose declared type marks `<X>?`).
+ *   - The interpolated field is declared optional in the file's local
+ *     type/interface declarations.
+ *
+ * Pragmatic narrowing: we hard-code `props` as the parameter name (the
+ * codebase convention for every CDK construct constructor) AND require the
+ * file to declare an interface or type alias with a field matching the
+ * interpolated name marked optional. This keeps the rule precise — required
+ * fields are never flagged, even though they sit at the same site.
+ *
+ * Known limitation (multi-interface false positive): `optionalFields` is a
+ * Set scoped to the whole `create()` call — every `TSInterfaceDeclaration`
+ * and `TSTypeAliasDeclaration` in the file adds to the same pool. If file F
+ * declares `interface PropsA { vpc?: T }` AND `interface PropsB { vpc: T }`
+ * and a class typed `PropsB` interpolates `props.vpc`, the rule fires
+ * spuriously because the optional `vpc` from `PropsA` taints the set. The
+ * shape has not appeared in production code under this rule's glob
+ * (`lib/{resources,patterns,config}/aws/**\/*.ts`) — every file in scope
+ * declares one props interface per construct. If a future file legitimately
+ * declares multiple props interfaces with overlapping field names, either
+ * (a) split into sibling files, or (b) extend the rule to track
+ * field-optionality per-interface via the constructor parameter's
+ * `typeAnnotation` (would require per-class scope tracking).
+ *
+ * Canonical fix: read the optional in the constructor, store on `this` with
+ * a fallback (`this.<name>Value = props.<X> ?? <fallback>`), then use
+ * `this.<name>Value` in every template-literal site. See
+ * `aiDocs/research/2026-05-17-review-deltas.md § "Fixes (this run)"` and
+ * `fjall/components/infrastructure/lib/resources/aws/database/rdsInstance.ts:119`.
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow optionally-typed `props.<X>` interpolation in CDK construct IDs (template-literal 2nd arg of `new ...`). Optional fields produce the literal string 'undefined' in CFN logical IDs when callers omit them.",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      optionalInConstructId:
+        "Construct ID interpolates `props.{{field}}` which is optionally typed; when the caller omits this field the literal string 'undefined' is baked into the CloudFormation logical ID. Resolve in the constructor (`this.{{field}}Value = props.{{field}} ?? <fallback>`) and use `this.{{field}}Value` here. See aiDocs/research/2026-05-17-review-deltas.md § M-9."
+    },
+    schema: []
+  },
+
+  create(context) {
+    const optionalFields = new Set();
+
+    function collectFromMembers(members) {
+      if (!Array.isArray(members)) return;
+      for (const member of members) {
+        if (
+          member.type === "TSPropertySignature" &&
+          member.optional === true &&
+          member.key &&
+          member.key.type === "Identifier"
+        ) {
+          optionalFields.add(member.key.name);
+        }
+      }
+    }
+
+    return {
+      TSInterfaceDeclaration(node) {
+        if (node.body) collectFromMembers(node.body.body);
+      },
+      TSTypeLiteral(node) {
+        collectFromMembers(node.members);
+      },
+      NewExpression(node) {
+        const constructId = node.arguments && node.arguments[1];
+        if (!constructId || constructId.type !== "TemplateLiteral") return;
+        for (const expr of constructId.expressions) {
+          if (
+            expr.type === "MemberExpression" &&
+            expr.computed === false &&
+            expr.object &&
+            expr.object.type === "Identifier" &&
+            expr.object.name === "props" &&
+            expr.property &&
+            expr.property.type === "Identifier" &&
+            optionalFields.has(expr.property.name)
+          ) {
+            context.report({
+              node: expr,
+              messageId: "optionalInConstructId",
+              data: { field: expr.property.name }
+            });
+          }
+        }
+      }
+    };
+  }
+};

package/no-vacuous-cdk-synth-regex.js

@@ -0,0 +1,109 @@
+/**
+ * ESLint Rule: no-vacuous-cdk-synth-regex
+ *
+ * Flags regex literals with NO metacharacters (no `.`, `*`, `+`, `?`, `^`,
+ * `$`, `[`, `\`, `(`, `|`) used inside `.test(...)` calls in test files.
+ * The bug shape: `expect(arr.some((id) => /BackupTaskTaskRole/.test(id))).toBe(false)`
+ * — the literal pattern claims to guard against an ID containing the
+ * concatenated tokens, but CDK synth output interleaves construct path
+ * segments between concept tokens (e.g. the actual synthesised logical ID
+ * is `ClickHouseComputeComputeClickHouseBackupTaskTaskDefinitionTaskRole40342F49`),
+ * so the literal pattern never matches and the assertion passes whether
+ * the regression has occurred or not.
+ *
+ * Per `.claude/rules/code-quality.md § "Regression Tests Must Distinguish
+ * from the Bug Shape"`. The 2026-05-10 ClickHouse review found this exact
+ * shape at `clickhouseBackup.test.ts:132`; the canonical fix replaced
+ * `/BackupTaskTaskRole/` with `/BackupTask.*TaskRole/` (allowing intervening
+ * synth-output segments). This rule shifts that detection left to author-time.
+ *
+ * Detection (heuristic):
+ *   1. File must be a test file (`*.test.ts`, `*.test.tsx`, or under `__tests__/`).
+ *   2. Node must be a regex Literal where `node.regex.pattern` matches
+ *      `^[A-Za-z0-9_]+$` (purely word chars; no metacharacters).
+ *   3. Pattern must contain at least one uppercase letter AND be at least
+ *      8 chars long (heuristic for "looks like a CDK construct ID token
+ *      concatenation" — filters out short literal regex like `/abc/` or
+ *      `/error/` that are usually fine).
+ *   4. Parent chain must be `<regex>.test(<arg>)` — i.e. the regex is the
+ *      object of a `.test()` member call.
+ *
+ * False-positive escape: developers can suppress with
+ * `// eslint-disable-next-line fjall/no-vacuous-cdk-synth-regex` on the line.
+ * Legitimate uses where the regex genuinely should match an exact substring
+ * with no synth-output interleaving (rare in CDK assertion contexts) are
+ * better expressed as `value.includes("...")` anyway.
+ *
+ * Detection ceiling: only regex Literals are walked. The constructor form
+ * `new RegExp("BackupTaskTaskRole").test(id)` bypasses detection because
+ * its pattern is a string expression, not a `Literal` node with a `.regex`
+ * property. CDK assertions almost never use the constructor form, but if
+ * they do, the same bug shape lands undetected — pair this rule with the
+ * "Regression Tests Must Distinguish from the Bug Shape" review discipline
+ * for any test pinning a synth-output assertion.
+ */
+
+const PATTERN_HEURISTIC = /^[A-Za-z0-9_]+$/;
+const HAS_UPPERCASE = /[A-Z]/;
+const MIN_PATTERN_LENGTH = 8;
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow literal-only regex (no wildcards) in `.test()` calls inside test files when the pattern looks like a CDK construct-ID token concatenation. CDK synth output interleaves construct path segments between concept tokens, so the literal regex silently never matches.",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      vacuousRegex:
+        'Literal regex `/{{pattern}}/` has no wildcards and looks like a CDK construct-ID token concatenation. CDK synth output interleaves construct path segments between concept tokens, so this literal pattern likely never matches the actual synthesised logical ID — the assertion would pass whether the regression has occurred or not. Either insert `.*` between concept tokens (e.g. `/Foo.*Bar/`) to allow intervening segments, or use `value.includes("{{pattern}}")` if you genuinely need an exact substring match. See .claude/rules/code-quality.md § "Regression Tests Must Distinguish from the Bug Shape".'
+    },
+    schema: []
+  },
+
+  create(context) {
+    const filename = context.filename ?? context.getFilename();
+    const isTestFile =
+      /\.test\.[cm]?[jt]sx?$/.test(filename) || /__tests__\//.test(filename);
+    if (!isTestFile) return {};
+
+    return {
+      Literal(node) {
+        if (!node.regex) return;
+        const pattern = node.regex.pattern;
+        if (!PATTERN_HEURISTIC.test(pattern)) return;
+        if (!HAS_UPPERCASE.test(pattern)) return;
+        if (pattern.length < MIN_PATTERN_LENGTH) return;
+
+        const parent = node.parent;
+        if (
+          !parent ||
+          parent.type !== "MemberExpression" ||
+          parent.object !== node ||
+          parent.property.type !== "Identifier" ||
+          parent.property.name !== "test"
+        ) {
+          return;
+        }
+
+        const grandparent = parent.parent;
+        if (
+          !grandparent ||
+          grandparent.type !== "CallExpression" ||
+          grandparent.callee !== parent
+        ) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "vacuousRegex",
+          data: { pattern }
+        });
+      }
+    };
+  }
+};