feat(eslint-plugin): add no-closure-in-durable-operations rule (#252)

- Add new rule to detect and prevent closure variable mutations in
durable operations (step, runInChildContext, waitForCondition,
waitForCallback)
- Rule allows reading closure variables but prevents assignments and
updates (=, +=, ++, --)
- Recursively tracks variable declarations across nested scopes
- Reorganize rules into subdirectories with rule implementation and
tests co-located
- Add unit tests covering mutations, reads, and scope handling
- Update README with new rule documentation and examples

**Limitations**:

1. Object/Array Mutations: The rule only catches direct assignments and
update expressions but misses property mutations:

```
let obj = { count: 0 };
await context.step(async () => {
  obj.count++; // ❌ Not detected but equally problematic
  obj.items.push(1); // ❌ Not detected
});
```

2. Destructuring Assignments:
```
let a = 1, b = 2;
await context.step(async () => {
  [a, b] = [b, a]; // ❌ Not detected
});
```

3. Performance Consideration: The walkNode function recursively
traverses the entire callback AST. For large callbacks, this could be
slow. I'll investigate ESLint's built-in visitor pattern instead of
manual traversal later.

5. Duplicate Error in Nested Cases: Nested operations report the error
twice (once for each level). This might be confusing to users - I'll
enhance it later to report at the innermost level.

Author: ParidelPooya

packages/aws-durable-execution-sdk-js-eslint-plugin/README.md

@@ -16,7 +16,8 @@ Add the plugin to your ESLint configuration:
 {
   "plugins": ["@aws/durable-execution-sdk-js-eslint-plugin"],
   "rules": {
-    "@aws/durable-execution-sdk-js-eslint-plugin/no-nested-durable-operations": "error"
+    "@aws/durable-execution-sdk-js-eslint-plugin/no-nested-durable-operations": "error",
+    "@aws/durable-execution-sdk-js-eslint-plugin/no-closure-in-durable-operations": "error"
   }
 }
 ```
@@ -65,22 +66,93 @@ const result = await context.runInChildContext("block1", async (childCtx) => {
 });
 ```
 
+### `no-closure-in-durable-operations`
+
+Prevents modifying closure variables inside durable operations. Reading closure variables is allowed.
+
+#### ❌ Incorrect
+
+```javascript
+const handler = withDurableExecution(
+  async (event: any, context: DurableContext) => {
+    let a = 2;
+    const result = await context.runInChildContext(
+      async (childContext: DurableContext) => {
+        const stepResult = await childContext.step(async () => {
+          // Error: Modifying 'a' from outer scope causes replay inconsistency
+          a = a + 1;
+          return "child step completed";
+        });
+        return stepResult;
+      },
+    );
+    return result;
+  },
+);
+```
+
+#### ✅ Correct
+
+```javascript
+const handler = withDurableExecution(
+  async (event: any, context: DurableContext) => {
+    let a = 2;
+    const result = await context.runInChildContext(
+      async (childContext: DurableContext) => {
+        const stepResult = await childContext.step(async () => {
+          // Reading 'a' is OK
+          const value = a + 1;
+          return value;
+        });
+        return stepResult;
+      },
+    );
+    return result;
+  },
+);
+
+// Or use local variables
+const handler = withDurableExecution(
+  async (event: any, context: DurableContext) => {
+    const result = await context.runInChildContext(
+      async (childContext: DurableContext) => {
+        const stepResult = await childContext.step(async () => {
+          let a = 2;
+          a = a + 1;
+          return "child step completed";
+        });
+        return stepResult;
+      },
+    );
+    return result;
+  },
+);
+```
+
 ## Supported Durable Operations
 
 The plugin detects these durable operations:
 
 - `step`
-- `wait`
-- `waitForCallback`
+- `runInChildContext`
 - `waitForCondition`
+- `waitForCallback`
+- `wait`
 - `parallel`
 - `map`
-- `runInChildContext`
 
-## Why This Rule?
+## Why These Rules?
+
+### No Nested Durable Operations
 
 Nesting durable operations with the same context object can cause runtime errors and unexpected behavior in AWS Lambda Durable Functions. This rule helps catch these issues at development time.
 
+### No Closure in Durable Operations
+
+During replay, durable functions skip already-executed steps. If a closure variable is modified inside a step, the modification won't occur during replay, causing different outcomes between initial execution and replay. This leads to non-deterministic behavior and potential bugs.
+
+Reading closure variables is safe because it doesn't change state. Only mutations (assignments, increments, decrements) are problematic.
+
 ## License
 
 Apache-2.0

packages/aws-durable-execution-sdk-js-eslint-plugin/jest.config.js

@@ -2,10 +2,6 @@ module.exports = {
   preset: "ts-jest",
   testEnvironment: "node",
   roots: ["<rootDir>/src"],
-  testMatch: ["**/__tests__/**/*.test.ts"],
-  collectCoverageFrom: [
-    "src/**/*.ts",
-    "!src/**/*.test.ts",
-    "!src/**/__tests__/**",
-  ],
+  testMatch: ["**/*.test.ts"],
+  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.test.ts"],
 };

packages/aws-durable-execution-sdk-js-eslint-plugin/src/index.ts

@@ -1,17 +1,20 @@
-import { noNestedDurableOperations } from "./rules/no-nested-durable-operations";
-import { noNonDeterministicOutsideStep } from "./rules/no-non-deterministic-outside-step";
+import { noNestedDurableOperations } from "./rules/no-nested-durable-operations/no-nested-durable-operations";
+import { noNonDeterministicOutsideStep } from "./rules/no-non-deterministic-outside-step/no-non-deterministic-outside-step";
+import { noClosureInDurableOperations } from "./rules/no-closure-in-durable-operations/no-closure-in-durable-operations";
 
 export = {
   rules: {
     "no-nested-durable-operations": noNestedDurableOperations,
     "no-non-deterministic-outside-step": noNonDeterministicOutsideStep,
+    "no-closure-in-durable-operations": noClosureInDurableOperations,
   },
   configs: {
     recommended: {
       plugins: ["@aws/durable-functions"],
       rules: {
         "@aws/durable-functions/no-nested-durable-operations": "error",
         "@aws/durable-functions/no-non-deterministic-outside-step": "error",
+        "@aws/durable-functions/no-closure-in-durable-operations": "error",
       },
     },
   },