eslint-cdk-plugin 3.4.4 → 3.4.6

package/src/rules/no-unused-props/visitor/direct-props-usage-visitor.ts

@@ -0,0 +1,145 @@
+import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/utils";
+
+import { IPropsUsageTracker } from "../props-usage-tracker";
+
+import { INodeVisitor } from "./interface/node-visitor";
+
+/**
+ * Visitor that tracks direct usage of the props parameter.
+ *
+ * This visitor detects various patterns where props is accessed directly:
+ * - `props.bucketName` - Property access
+ * - `const { bucketName } = props` - Destructuring assignment
+ * - `this.bucketName = props.bucketName` - Assignment expression
+ * - `console.log(props)` - Whole object usage (marks all properties as used)
+ *
+ * @example
+ * ```typescript
+ * constructor(scope: Construct, id: string, props: MyConstructProps) {
+ *   super(scope, id);
+ *   const name = props.bucketName;           // <- Detected by visitMemberExpression
+ *   const { enableVersioning } = props;      // <- Detected by visitVariableDeclarator
+ *   this.name = props.bucketName;            // <- Detected by visitAssignmentExpression
+ *   console.log(props);                      // <- Detected by visitIdentifier (marks all)
+ * }
+ * ```
+ */
+export class DirectPropsUsageVisitor implements INodeVisitor {
+  constructor(
+    private readonly tracker: IPropsUsageTracker,
+    private readonly propsParamName: string
+  ) {}
+
+  visitMemberExpression(node: TSESTree.MemberExpression): void {
+    this.tracker.markAsUsedForMemberExpression(node, this.propsParamName);
+  }
+
+  visitVariableDeclarator(node: TSESTree.VariableDeclarator): void {
+    this.tracker.markAsUsedForVariableDeclarator(node, this.propsParamName);
+  }
+
+  visitAssignmentExpression(node: TSESTree.AssignmentExpression): void {
+    this.tracker.markAsUsedForAssignmentExpression(node, this.propsParamName);
+  }
+
+  visitIdentifier(node: TSESTree.Identifier): void {
+    /**
+     * Handles cases where the props identifier is used as a whole value.
+     *
+     * This method detects when `props` (or the configured propsParamName) is used
+     * in contexts where all properties should be marked as used, because we cannot
+     * statically determine which properties will be accessed at runtime.
+     *
+     * Handled patterns:
+     *
+     * 1. **External function call** (`someFunction(props)` or `console.log(props)`):
+     *    - Marks ALL properties as used
+     *    - Excludes `this.method(props)` which is handled by analyzePrivateMethodsCalledFromConstructor
+     *
+     *    AST structure:
+     *      CallExpression
+     *      ├── callee: Identifier (someFunction) or MemberExpression (console.log)
+     *      └── arguments: [Identifier (name: "props")]
+     *
+     * 2. **Return statement** (`return props`):
+     *    - Marks ALL properties as used
+     *
+     *    AST structure:
+     *      ReturnStatement
+     *      └── argument: Identifier (name: "props")
+     *
+     * 3. **Array element** (`[props]` or `[a, props, b]`):
+     *    - Marks ALL properties as used
+     *
+     *    AST structure:
+     *      ArrayExpression
+     *      └── elements: [..., Identifier (name: "props"), ...]
+     *
+     * 4. **Object property value** (`{ key: props }`):
+     *    - Marks ALL properties as used
+     *
+     *    AST structure:
+     *      Property
+     *      ├── key: Identifier (name: "key")
+     *      └── value: Identifier (name: "props")
+     *
+     * The following cases are intentionally excluded (handled elsewhere):
+     * - `props.xxx` (MemberExpression) - handled by visitMemberExpression
+     * - `const { xxx } = props` (VariableDeclarator with ObjectPattern) - handled by visitVariableDeclarator
+     * - `this.xxx = props.xxx` (AssignmentExpression) - handled by visitAssignmentExpression
+     * - `this.method(props)` (CallExpression with ThisExpression callee) - handled by analyzePrivateMethodsCalledFromConstructor
+     * - `const a = props` (alias registration) - handled by PropsAliasVisitor
+     */
+
+    // NOTE: Check if props object is used as a whole (e.g., console.log(props))
+    if (node.name !== this.propsParamName) return;
+
+    const parent = node.parent;
+    if (!parent) return;
+
+    switch (parent.type) {
+      // NOTE: Pattern 1: External function call
+      case AST_NODE_TYPES.CallExpression: {
+        if (!parent.arguments.includes(node)) return;
+        if (
+          parent.callee.type === AST_NODE_TYPES.MemberExpression &&
+          parent.callee.object.type === AST_NODE_TYPES.ThisExpression
+        ) {
+          return;
+        }
+        this.tracker.markAllAsUsed();
+        return;
+      }
+
+      // NOTE: Pattern 2: Return statement
+      case AST_NODE_TYPES.ReturnStatement: {
+        // NOTE: return props - props as a whole
+        if (parent.argument === node) {
+          this.tracker.markAllAsUsed();
+        }
+        return;
+      }
+
+      // NOTE: Pattern 3: Array element
+      case AST_NODE_TYPES.ArrayExpression: {
+        // NOTE: [props] - props as a whole
+        if (parent.elements.includes(node)) {
+          this.tracker.markAllAsUsed();
+        }
+        return;
+      }
+
+      // NOTE: Pattern 4: Object property value
+      case AST_NODE_TYPES.Property: {
+        // NOTE: { key: props } - props as a whole
+        if (parent.value === node) {
+          this.tracker.markAllAsUsed();
+        }
+        return;
+      }
+      default: {
+        return;
+      }
+    }
+  }
+}

package/src/rules/no-unused-props/visitor/index.ts

@@ -0,0 +1,5 @@
+export { DirectPropsUsageVisitor } from "./direct-props-usage-visitor";
+export { InstanceVariableUsageVisitor } from "./instance-variable-usage-visitor";
+export { MethodCallCollectorVisitor } from "./method-call-collector-visitor";
+export { PropsAliasVisitor } from "./props-alias-visitor";
+export { traverseNodes } from "./traverse-nodes";

package/src/rules/no-unused-props/visitor/instance-variable-usage-visitor.ts

@@ -0,0 +1,117 @@
+import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/utils";
+
+import { IPropsUsageTracker } from "../props-usage-tracker";
+
+import { INodeVisitor } from "./interface/node-visitor";
+
+/**
+ * Visitor that tracks props usage through instance variables.
+ *
+ * When props is assigned to an instance variable (e.g., `this.myProps = props`),
+ * this visitor tracks property access on that instance variable throughout the class.
+ *
+ * Handles two patterns:
+ * 1. Property access: `this.myProps.bucketName` - marks specific property as used
+ * 2. Whole object usage: `console.log(this.myProps)` - marks all properties as used
+ *
+ * @example
+ * ```typescript
+ * class MyConstruct extends Construct {
+ *   private myProps: MyConstructProps;
+ *
+ *   constructor(scope: Construct, id: string, props: MyConstructProps) {
+ *     super(scope, id);
+ *     this.myProps = props;
+ *   }
+ *
+ *   someMethod() {
+ *     console.log(this.myProps.bucketName);  // <- 'bucketName' is marked as used
+ *   }
+ * }
+ * ```
+ */
+export class InstanceVariableUsageVisitor implements INodeVisitor {
+  constructor(
+    private readonly tracker: IPropsUsageTracker,
+    private readonly instanceVarName: string
+  ) {}
+
+  visitMemberExpression(node: TSESTree.MemberExpression): void {
+    // ===========================================================================
+    // Pattern 1: Property access - this.instanceVarName.propertyName
+    // ===========================================================================
+    // Matches code like: `console.log(this.myProps.bucketName)` or `return this.myProps.enableVersioning`
+    //
+    // AST structure:
+    //   MemberExpression (node)
+    //   ├── object: MemberExpression (this.myProps)
+    //   │   ├── object: ThisExpression
+    //   │   └── property: Identifier (name: "myProps" === instanceVarName)
+    //   └── property: Identifier (name: "bucketName" - the property being accessed)
+    //
+    // When this pattern matches, we mark the accessed property (e.g., "bucketName") as used.
+    if (
+      node.type === AST_NODE_TYPES.MemberExpression &&
+      node.object.type === AST_NODE_TYPES.MemberExpression &&
+      node.object.object.type === AST_NODE_TYPES.ThisExpression &&
+      node.object.property.type === AST_NODE_TYPES.Identifier &&
+      node.object.property.name === this.instanceVarName &&
+      node.property.type === AST_NODE_TYPES.Identifier
+    ) {
+      this.tracker.markAsUsed(node.property.name);
+      return;
+    }
+
+    // ===========================================================================
+    // Pattern 2: Whole object usage - this.instanceVarName used as a value
+    // ===========================================================================
+    // Matches code like: `console.log(this.myProps)` or `return this.myProps`
+    //
+    // AST structure:
+    //   MemberExpression (node)
+    //   ├── object: ThisExpression
+    //   └── property: Identifier (name: "myProps" === instanceVarName)
+    //
+    // However, we need to exclude certain cases where `this.myProps` appears
+    // but isn't actually being "used as a value":
+    //
+    // Exclusion A: Property access (handled by Pattern 1 above)
+    //   Code: `this.myProps.bucketName`
+    //   The `this.myProps` part has parent MemberExpression where it's the object
+    //
+    // Exclusion B: Assignment left-hand side
+    //   Code: `this.myProps = props`
+    //   The `this.myProps` is being assigned to, not used as a value
+    if (
+      node.type === AST_NODE_TYPES.MemberExpression &&
+      node.object.type === AST_NODE_TYPES.ThisExpression &&
+      node.property.type === AST_NODE_TYPES.Identifier &&
+      node.property.name === this.instanceVarName
+    ) {
+      const parent = node.parent;
+
+      // NOTE: Exclusion A - Skip if this is part of a property access (this.myProps.xxx)
+      // The parent MemberExpression's object being this node means we're accessing a property
+      if (
+        parent?.type === AST_NODE_TYPES.MemberExpression &&
+        parent.object === node
+      ) {
+        return;
+      }
+
+      // NOTE: Exclusion B - Skip if this is the left side of an assignment (this.myProps = ...)
+      if (
+        parent?.type === AST_NODE_TYPES.AssignmentExpression &&
+        parent.left === node
+      ) {
+        return;
+      }
+
+      // NOTE: If we reach here, `this.myProps` is used as a whole value
+      // Examples: console.log(this.myProps), return this.myProps, [this.myProps], etc.
+      // Since we can't know which properties will be accessed at runtime, mark all as used
+      this.tracker.markAllAsUsed();
+      return;
+    }
+  }
+}

package/src/rules/no-unused-props/visitor/interface/node-visitor.ts

@@ -0,0 +1,9 @@
+import { TSESTree } from "@typescript-eslint/utils";
+
+export interface INodeVisitor {
+  visitMemberExpression?(node: TSESTree.MemberExpression): void;
+  visitVariableDeclarator?(node: TSESTree.VariableDeclarator): void;
+  visitAssignmentExpression?(node: TSESTree.AssignmentExpression): void;
+  visitIdentifier?(node: TSESTree.Identifier): void;
+  visitCallExpression?(node: TSESTree.CallExpression): void;
+}

package/src/rules/no-unused-props/visitor/method-call-collector-visitor.ts

@@ -0,0 +1,60 @@
+import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/utils";
+
+import { INodeVisitor } from "./interface/node-visitor";
+
+type MethodCallInfo = {
+  methodName: string;
+  propsArgIndices: number[];
+};
+
+/**
+ * Visitor that collects method calls where props is passed as an argument.
+ *
+ * This visitor detects patterns like:
+ * - `this.someMethod(props)`
+ * - `this.someMethod(a, props, b)` (props at any position)
+ *
+ * AST structure for `this.someMethod(props)`:
+ *   CallExpression
+ *   ├── callee: MemberExpression
+ *   │   ├── object: ThisExpression
+ *   │   └── property: Identifier (name: "someMethod")
+ *   └── arguments: [Identifier (name: "props")]
+ *
+ * The collected information is used by analyzePrivateMethodsCalledFromConstructor
+ * to analyze the method bodies and track props usage within them.
+ */
+export class MethodCallCollectorVisitor implements INodeVisitor {
+  private readonly _result: MethodCallInfo[] = [];
+
+  constructor(private readonly propsParamName: string) {}
+
+  visitCallExpression(node: TSESTree.CallExpression): void {
+    // NOTE: Check for this.methodName(...) pattern
+    if (
+      node.callee.type !== AST_NODE_TYPES.MemberExpression ||
+      node.callee.object.type !== AST_NODE_TYPES.ThisExpression ||
+      node.callee.property.type !== AST_NODE_TYPES.Identifier
+    ) {
+      return;
+    }
+
+    const methodName = node.callee.property.name;
+    const propsArgIndices = node.arguments.reduce<number[]>(
+      (acc, arg, index) =>
+        arg.type === AST_NODE_TYPES.Identifier &&
+        arg.name === this.propsParamName
+          ? [...acc, index]
+          : acc,
+      []
+    );
+
+    if (propsArgIndices.length) {
+      this._result.push({ methodName, propsArgIndices });
+    }
+  }
+
+  get result(): MethodCallInfo[] {
+    return this._result;
+  }
+}

package/src/rules/no-unused-props/visitor/props-alias-visitor.ts

@@ -0,0 +1,81 @@
+import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/utils";
+
+import { IPropsUsageTracker } from "../props-usage-tracker";
+
+import { INodeVisitor } from "./interface/node-visitor";
+
+/**
+ * Visitor that tracks props usage through variable aliases.
+ *
+ * When props is assigned to another variable (alias), this visitor:
+ * 1. Registers the alias when `const myProps = props` is detected
+ * 2. Tracks property access on the alias like `myProps.bucketName`
+ *
+ * @example
+ * ```typescript
+ * constructor(scope: Construct, id: string, props: MyConstructProps) {
+ *   super(scope, id);
+ *   const myProps = props;              // <- Alias 'myProps' is registered
+ *   console.log(myProps.bucketName);    // <- 'bucketName' is marked as used
+ * }
+ * ```
+ */
+export class PropsAliasVisitor implements INodeVisitor {
+  private readonly aliases = new Set<string>();
+
+  constructor(
+    private readonly tracker: IPropsUsageTracker,
+    private readonly propsParamName: string
+  ) {}
+
+  visitMemberExpression(node: TSESTree.MemberExpression): void {
+    this.tracker.markAsUsedForMemberExpression(node, this.propsParamName);
+    /**
+     * NOTE: Check if the object is an alias of props
+     * ```ts
+     * const myProps = props;
+     * console.log(myProps.bucketName); // <- detect this access
+     * ```
+     */
+    if (
+      node.object.type === AST_NODE_TYPES.Identifier &&
+      this.aliases.has(node.object.name) &&
+      node.property.type === AST_NODE_TYPES.Identifier
+    ) {
+      this.tracker.markAsUsed(node.property.name);
+    }
+  }
+
+  visitIdentifier(node: TSESTree.Identifier): void {
+    /**
+     * Handles alias registration for props.
+     *
+     * This method detects when props is assigned to a simple variable,
+     * which creates an alias that should be tracked for property access.
+     *
+     * Handled pattern:
+     *
+     * **Variable assignment** (`const myProps = props`):
+     *    - Registers 'myProps' as an alias of props
+     *    - Later access like `myProps.bucketName` will be detected by visitMemberExpression
+     *
+     *    AST structure:
+     *      VariableDeclarator
+     *      ├── id: Identifier (name: "myProps" - the alias to register)
+     *      └── init: Identifier (name: "props")
+     */
+    if (node.name !== this.propsParamName) return;
+
+    const parent = node.parent;
+    if (!parent) return;
+
+    // NOTE: const myProps = props - track 'myProps' as an alias of props
+    if (
+      parent.type === AST_NODE_TYPES.VariableDeclarator &&
+      parent.init === node &&
+      parent.id.type === AST_NODE_TYPES.Identifier
+    ) {
+      this.aliases.add(parent.id.name);
+    }
+  }
+}

package/src/rules/no-unused-props/visitor/traverse-nodes.ts

@@ -0,0 +1,38 @@
+import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/utils";
+
+import { findChildNodes } from "../../../core/ast-node/finder/child-nodes";
+
+import { INodeVisitor } from "./interface/node-visitor";
+
+export const traverseNodes = (
+  node: TSESTree.Node,
+  visitor: INodeVisitor
+): void => {
+  switch (node.type) {
+    case AST_NODE_TYPES.MemberExpression: {
+      visitor.visitMemberExpression?.(node);
+      break;
+    }
+    case AST_NODE_TYPES.VariableDeclarator: {
+      visitor.visitVariableDeclarator?.(node);
+      break;
+    }
+    case AST_NODE_TYPES.AssignmentExpression: {
+      visitor.visitAssignmentExpression?.(node);
+      break;
+    }
+    case AST_NODE_TYPES.Identifier: {
+      visitor.visitIdentifier?.(node);
+      break;
+    }
+    case AST_NODE_TYPES.CallExpression: {
+      visitor.visitCallExpression?.(node);
+      break;
+    }
+  }
+
+  // NOTE: Recursively visit child nodes
+  for (const child of findChildNodes(node)) {
+    traverseNodes(child, visitor);
+  }
+};

package/src/rules/no-variable-construct-id.ts

@@ -5,9 +5,9 @@ import {
   TSESTree,
 } from "@typescript-eslint/utils";
 
-import { createRule } from "../utils/createRule";
-import { getConstructorPropertyNames } from "../utils/getPropertyNames";
-import { isConstructType } from "../utils/typecheck/cdk";
+import { isConstructType } from "../core/cdk-construct/type-checker/is-construct";
+import { findConstructorPropertyNames } from "../core/ts-type/finder/constructor-property-name";
+import { createRule } from "../shared/create-rule";
 
 type Context = TSESLint.RuleContext<"invalidConstructId", []>;
 
@@ -37,7 +37,7 @@ export const noVariableConstructId = createRule({
 
         if (!isConstructType(type) || node.arguments.length < 2) return;
 
-        const constructorPropertyNames = getConstructorPropertyNames(type);
+        const constructorPropertyNames = findConstructorPropertyNames(type);
         if (constructorPropertyNames[1] !== "id") return;
 
         validateConstructId(node, context);

package/src/rules/pascal-case-construct-id.ts

@@ -5,10 +5,10 @@ import {
   TSESTree,
 } from "@typescript-eslint/utils";
 
-import { toPascalCase } from "../utils/convertString";
-import { createRule } from "../utils/createRule";
-import { getConstructorPropertyNames } from "../utils/getPropertyNames";
-import { isConstructOrStackType } from "../utils/typecheck/cdk";
+import { isConstructOrStackType } from "../core/cdk-construct/type-checker/is-construct-or-stack";
+import { findConstructorPropertyNames } from "../core/ts-type/finder/constructor-property-name";
+import { toPascalCase } from "../shared/converter/to-pascal-case";
+import { createRule } from "../shared/create-rule";
 
 const QUOTE_TYPE = {
   SINGLE: "'",
@@ -48,7 +48,7 @@ export const pascalCaseConstructId = createRule({
           return;
         }
 
-        const constructorPropertyNames = getConstructorPropertyNames(type);
+        const constructorPropertyNames = findConstructorPropertyNames(type);
         if (constructorPropertyNames[1] !== "id") return;
 
         validateConstructId(node, context);

package/src/rules/props-name-convention.ts

@@ -1,8 +1,8 @@
 import { AST_NODE_TYPES, ESLintUtils } from "@typescript-eslint/utils";
 
-import { createRule } from "../utils/createRule";
-import { getConstructor } from "../utils/getConstructor";
-import { isConstructType } from "../utils/typecheck/cdk";
+import { findConstructor } from "../core/ast-node/finder/constructor";
+import { isConstructType } from "../core/cdk-construct/type-checker/is-construct";
+import { createRule } from "../shared/create-rule";
 
 /**
  * Enforces a naming convention for props interfaces in Construct classes
@@ -34,7 +34,7 @@ export const propsNameConvention = createRule({
         if (!isConstructType(type)) return;
 
         // NOTE: check constructor parameter
-        const constructor = getConstructor(node);
+        const constructor = findConstructor(node);
         if (!constructor) return;
 
         const propsParam = constructor.value.params?.[2];

package/src/rules/require-jsdoc.ts

@@ -4,8 +4,8 @@ import {
   ESLintUtils,
 } from "@typescript-eslint/utils";
 
-import { createRule } from "../utils/createRule";
-import { isConstructType } from "../utils/typecheck/cdk";
+import { isConstructType } from "../core/cdk-construct/type-checker/is-construct";
+import { createRule } from "../shared/create-rule";
 
 /**
  * Require JSDoc comments for interface properties and public properties in Construct classes

package/src/rules/require-passing-this.ts

@@ -4,9 +4,9 @@ import {
   TSESLint,
 } from "@typescript-eslint/utils";
 
-import { createRule } from "../utils/createRule";
-import { getConstructorPropertyNames } from "../utils/getPropertyNames";
-import { isConstructType } from "../utils/typecheck/cdk";
+import { isConstructType } from "../core/cdk-construct/type-checker/is-construct";
+import { findConstructorPropertyNames } from "../core/ts-type/finder/constructor-property-name";
+import { createRule } from "../shared/create-rule";
 
 type Option = {
   allowNonThisAndDisallowScope?: boolean;
@@ -63,7 +63,7 @@ export const requirePassingThis = createRule({
         if (argument.type === AST_NODE_TYPES.ThisExpression) return;
 
         // NOTE: If the first argument is not `scope`, it's valid
-        const constructorPropertyNames = getConstructorPropertyNames(type);
+        const constructorPropertyNames = findConstructorPropertyNames(type);
         if (constructorPropertyNames[0] !== "scope") return;
 
         // NOTE: If `allowNonThisAndDisallowScope` is false, require `this` for all cases

package/src/rules/require-props-default-doc.ts

@@ -1,6 +1,6 @@
 import { AST_NODE_TYPES, AST_TOKEN_TYPES } from "@typescript-eslint/utils";
 
-import { createRule } from "../utils/createRule";
+import { createRule } from "../shared/create-rule";
 
 /**
  * Requires @default JSDoc documentation for optional properties in interfaces ending with 'Props'