@fjall/eslint-plugin 2.30.3 → 2.31.1

package/index.js

@@ -23,6 +23,7 @@ import noL2AsgLifecycleHook from "./no-l2-asg-lifecycle-hook.js";
 import noTierStageConflation from "./no-tier-stage-conflation.js";
 import noBareSdkAbortTimeout from "./no-bare-sdk-abort-timeout.js";
 import requireAbortPrecheckInSdkLoop from "./require-abort-precheck-in-sdk-loop.js";
+import requireAbortCompositionOnSdkSend from "./require-abort-composition-on-sdk-send.js";
 import noClassicConnectedAccountAssume from "./no-classic-connected-account-assume.js";
 import noRawDbTransaction from "./no-raw-db-transaction.js";
 
@@ -55,6 +56,7 @@ export default {
     "no-tier-stage-conflation": noTierStageConflation,
     "no-bare-sdk-abort-timeout": noBareSdkAbortTimeout,
     "require-abort-precheck-in-sdk-loop": requireAbortPrecheckInSdkLoop,
+    "require-abort-composition-on-sdk-send": requireAbortCompositionOnSdkSend,
     "no-classic-connected-account-assume": noClassicConnectedAccountAssume,
     "no-raw-db-transaction": noRawDbTransaction
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/eslint-plugin",
-  "version": "2.30.3",
+  "version": "2.31.1",
   "description": "ESLint plugin with Fjall-specific coding standard rules",
   "type": "module",
   "main": "index.js",
@@ -32,5 +32,5 @@
     "vitest": "^4.1.5"
   },
   "license": "SEE LICENSE IN LICENSE",
-  "gitHead": "d398edc0c0edf661d7ab6e5a47623529f68dfd2a"
+  "gitHead": "a48cfaf6e050ce1736837802dfcaf517ba39f199"
 }

package/require-abort-composition-on-sdk-send.js

@@ -0,0 +1,142 @@
+/**
+ * ESLint Rule: require-abort-composition-on-sdk-send
+ *
+ * The presence half of the three-rule deploy-core abort contract.
+ * no-bare-sdk-abort-timeout enforces the composition QUALITY half (no bare
+ * AbortSignal.timeout where an abort option exists) and
+ * require-abort-precheck-in-sdk-loop the pagination PRE-CHECK half. THIS rule
+ * enforces PRESENCE: an AWS SDK `.send()` carrying a Command argument MUST
+ * pass an options argument with an `abortSignal` property. A zero-option
+ * `client.send(command)` composes nothing — it can neither time out nor abort
+ * on caller shutdown, so it can hang forever (worse than the bare-timeout
+ * class the sibling rule catches). Pass
+ * `{ abortSignal: composeSdkAbortSignal(abortSignal) }` from
+ * `deploy-core/src/aws/organisations/types.ts` and thread the caller's
+ * signal; `composeSdkAbortSignal(undefined)` still bounds the call with the
+ * default timeout when no caller signal exists.
+ *
+ * SDK-send predicate (syntactic, no type info): the first argument is
+ * "commandish" — a `new XxxCommand(...)` expression, or an identifier whose
+ * declaration init is one (resolved via a scope-chain walk). Non-SDK sends
+ * (`res.send(html)`, `process.send(msg)`, EventEmitter/WebSocket
+ * `.send(payload)`) never take a Command-constructed first argument, so the
+ * predicate keeps them out of scope.
+ *
+ * Exempt (deliberate false-negative bias, mirroring the leniency rationale in
+ * require-abort-precheck-in-sdk-loop):
+ *  - Second argument that is an identifier/call/conditional — opaque without
+ *    data-flow analysis; options built elsewhere may well carry the signal.
+ *  - Options object containing a spread — the abortSignal may ride in on it.
+ *
+ * No fixer — the correct fix is a signature-threading judgement (which caller
+ * signal to thread, through how many layers), like both siblings.
+ *
+ * Per .claude/rules/robustness-standards.md § "SDK probe helpers take optional
+ * abortSignal and compose with the timeout".
+ */
+
+const COMMAND_NAME_RE = /Command$/;
+
+function isCommandNew(node) {
+  return (
+    node !== null &&
+    node !== undefined &&
+    node.type === "NewExpression" &&
+    node.callee.type === "Identifier" &&
+    COMMAND_NAME_RE.test(node.callee.name)
+  );
+}
+
+function findVariableInScopeChain(scope, name) {
+  let s = scope;
+  while (s) {
+    const v = s.variables.find((v) => v.name === name);
+    if (v) return v;
+    s = s.upper;
+  }
+  return null;
+}
+
+/**
+ * True when the first `.send()` argument is "commandish": a
+ * `new XxxCommand(...)` expression directly, or an identifier whose
+ * declaration init is one.
+ */
+function isCommandish(node, sourceCode) {
+  if (isCommandNew(node)) return true;
+  if (node.type !== "Identifier") return false;
+  const scope = sourceCode.getScope(node);
+  const variable = findVariableInScopeChain(scope, node.name);
+  if (!variable) return false;
+  return variable.defs.some(
+    (def) =>
+      def.type === "Variable" &&
+      def.node.type === "VariableDeclarator" &&
+      isCommandNew(def.node.init)
+  );
+}
+
+/**
+ * True when the options ObjectExpression carries an `abortSignal` property or
+ * any spread (a spread may carry the signal in — exempt, per the
+ * false-negative bias above).
+ */
+function hasAbortSignalOrSpread(objectExpression) {
+  return objectExpression.properties.some(
+    (prop) =>
+      prop.type === "SpreadElement" ||
+      (prop.type === "Property" &&
+        !prop.computed &&
+        ((prop.key.type === "Identifier" && prop.key.name === "abortSignal") ||
+          (prop.key.type === "Literal" && prop.key.value === "abortSignal")))
+  );
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require an abortSignal option on every Command-carrying SDK .send() — the presence half of the abort contract.",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      missingSendOptions:
+        "This SDK .send() passes a Command but no options argument — nothing composes an abort signal, so the call can neither time out nor abort on caller shutdown (it can hang forever). Pass { abortSignal: composeSdkAbortSignal(abortSignal) } from organisations/types.js and thread the caller's abortSignal; composeSdkAbortSignal(undefined) still bounds the call when no caller signal exists.",
+      optionsMissingAbortSignal:
+        "This SDK .send() options object carries no abortSignal — nothing composes an abort signal, so the call can neither time out nor abort on caller shutdown. Add abortSignal: composeSdkAbortSignal(abortSignal) from organisations/types.js and thread the caller's abortSignal. If this send is genuinely signal-free, add an eslint-disable with a reason."
+    },
+    schema: []
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type !== "MemberExpression" ||
+          node.callee.computed ||
+          node.callee.property.type !== "Identifier" ||
+          node.callee.property.name !== "send"
+        ) {
+          return;
+        }
+        const commandArg = node.arguments[0];
+        if (commandArg === undefined) return;
+        if (!isCommandish(commandArg, sourceCode)) return;
+
+        if (node.arguments.length === 1) {
+          context.report({ node, messageId: "missingSendOptions" });
+          return;
+        }
+        const options = node.arguments[1];
+        if (options.type !== "ObjectExpression") return;
+        if (hasAbortSignalOrSpread(options)) return;
+        context.report({ node, messageId: "optionsMissingAbortSignal" });
+      }
+    };
+  }
+};