@fjall/eslint-plugin 2.18.1

package/prefer-with-agent-flags.js

@@ -0,0 +1,64 @@
+/**
+ * ESLint Rule: prefer-with-agent-flags
+ *
+ * Inline declarations of the four canonical agent flags
+ * (`--agent`, `--budget`, `--fields`, `--full`) MUST go through
+ * `withAgentFlags()` from `cli/src/commands/registration/helpers.ts`.
+ *
+ * The 2026-04-28 /review of the MCP infra-app-creation branch found this
+ * drift twice in one week — once in `infrastructureCommands.ts`, once in
+ * `apiCommands.ts`. The helper is the single source of truth for flag
+ * descriptions; inline drift produces inconsistent `--help` output across
+ * subcommands. See `.claude/rules/cli-standards.md` for context.
+ *
+ * Detects: `.option("--<agent-flag>", ...)` calls in registration files,
+ * excluding `helpers.ts` itself (which legitimately defines the helper).
+ */
+
+const AGENT_FLAGS = new Set(["--agent", "--budget", "--fields", "--full"]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Agent flags (--agent/--budget/--fields/--full) must be registered via withAgentFlags(), not inline.",
+      category: "Best Practices",
+      recommended: false
+    },
+    messages: {
+      preferHelper:
+        "Use withAgentFlags() from ./helpers.js instead of declaring `{{flag}}` inline. The helper is the single source of truth for the four agent flags."
+    },
+    schema: []
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        const callee = node.callee;
+        if (callee.type !== "MemberExpression") return;
+        if (
+          callee.property.type !== "Identifier" ||
+          callee.property.name !== "option"
+        ) {
+          return;
+        }
+        const firstArg = node.arguments[0];
+        if (!firstArg) return;
+        if (firstArg.type !== "Literal" || typeof firstArg.value !== "string") {
+          return;
+        }
+        const flag = firstArg.value.split(/[ ,]/, 1)[0];
+        if (AGENT_FLAGS.has(flag)) {
+          context.report({
+            node: firstArg,
+            messageId: "preferHelper",
+            data: { flag }
+          });
+        }
+      }
+    };
+  }
+};

package/require-abort-precheck-in-sdk-loop.js

@@ -0,0 +1,169 @@
+/**
+ * ESLint Rule: require-abort-precheck-in-sdk-loop
+ *
+ * Complements no-bare-sdk-abort-timeout. That rule enforces the timeout-
+ * COMPOSITION half of the SDK-probe abort contract (every send routes through
+ * composeSdkAbortSignal so an in-flight call aborts on shutdown). THIS rule
+ * enforces the pagination-PRE-CHECK half: a sequential loop that issues a
+ * composed SDK send (composeSdkAbortSignal with a real caller signal) MUST
+ * pre-check the abort state between iterations — `isAborted(signal)` or a
+ * `signal.aborted` read that can break/return/throw. Without it, on shutdown the
+ * loop keeps starting fast-failing sends across every remaining iteration
+ * rather than breaking cleanly (the scanAccountDelivery class — the lone
+ * non-conformer the composition rule could not see).
+ *
+ * Exempt (no flag):
+ *  - No-caller-signal sends — composeSdkAbortSignal(undefined, ...) or
+ *    composeSdkAbortSignal() — there is no signal to check, so a pre-check would
+ *    be dead ceremony ("justify ceremony or drop it").
+ *  - Concurrent sends inside a nested function/callback (.map(async …)), where a
+ *    per-iteration pre-check does not apply — the sends fire together and the
+ *    composed signal aborts them.
+ *  - Single (non-loop) sends — the composed signal alone bounds shutdown.
+ *
+ * Per .claude/rules/robustness-standards.md § "SDK probe helpers take optional
+ * abortSignal and compose with the timeout" — "pre-check isAborted between pages
+ * of paginated loops".
+ */
+
+const LOOP_TYPES = new Set([
+  "ForStatement",
+  "ForOfStatement",
+  "ForInStatement",
+  "WhileStatement",
+  "DoWhileStatement"
+]);
+
+const FUNCTION_TYPES = new Set([
+  "FunctionDeclaration",
+  "FunctionExpression",
+  "ArrowFunctionExpression"
+]);
+
+/**
+ * A composeSdkAbortSignal(signal, …) call whose first argument is a real caller
+ * signal — not `undefined` and not absent. These are the sends that need a
+ * between-iteration pre-check.
+ *
+ * The Identifier-callee match is deliberate: the helper is always imported and
+ * called bare across deploy-core/cli (no namespaced `ns.composeSdkAbortSignal()`
+ * call sites exist, and the bare import is the convention the companion
+ * no-bare-sdk-abort-timeout rule steers toward). Extend to MemberExpression
+ * only if a namespaced call ever lands — speculative coverage now would be
+ * defending a shape that does not exist.
+ */
+function isComposedSendWithRealSignal(node) {
+  if (
+    node.type !== "CallExpression" ||
+    node.callee.type !== "Identifier" ||
+    node.callee.name !== "composeSdkAbortSignal"
+  ) {
+    return false;
+  }
+  const firstArg = node.arguments[0];
+  if (firstArg === undefined) return false;
+  if (firstArg.type === "Identifier" && firstArg.name === "undefined") {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * An `isAborted(...)` call or any `.aborted` member read — an abort guard.
+ *
+ * Mere presence counts; the guard is not required to sit in a conditional that
+ * provably breaks/returns/throws. This leniency is deliberate: tightening to
+ * "must be in conditional position" would false-positive the common
+ * assign-then-branch shape (`const stop = isAborted(sig); if (stop) break;`),
+ * and catching a genuinely-discarded read without that false positive needs
+ * full data-flow analysis — disproportionate here. The rule errs toward a rare
+ * false-negative (a discarded read) over flagging correct code.
+ */
+function isAbortGuard(node) {
+  if (
+    node.type === "CallExpression" &&
+    node.callee.type === "Identifier" &&
+    node.callee.name === "isAborted"
+  ) {
+    return true;
+  }
+  return (
+    node.type === "MemberExpression" &&
+    !node.computed &&
+    node.property.type === "Identifier" &&
+    node.property.name === "aborted"
+  );
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require an isAborted pre-check inside a sequential loop that issues a composed SDK send — the pagination half of the abort contract.",
+      category: "Possible Errors",
+      recommended: true
+    },
+    messages: {
+      missingAbortPrecheck:
+        "This loop issues a composed SDK send (composeSdkAbortSignal with a caller signal) but never pre-checks abort between iterations — on shutdown it keeps starting fast-failing sends across every remaining iteration instead of breaking cleanly. Add `if (isAborted(signal)) break;` (or a signal.aborted check) at the top of the loop body, matching listAccounts in organisations/accounts.ts. If this loop genuinely cannot benefit, add an eslint-disable with a reason."
+    },
+    schema: []
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const visitorKeys = sourceCode.visitorKeys;
+
+    /**
+     * Depth-first search of `root`'s subtree for a node matching `predicate`.
+     * When `stopAtLoopsAndFns` is true, nested loop/function subtrees are not
+     * descended into (so a send is attributed to its innermost enclosing loop,
+     * and a guard inside a deeper nested scope does not count for this loop).
+     */
+    function subtreeHas(root, predicate, stopAtLoopsAndFns) {
+      if (!root) return false;
+      const stack = [{ node: root, isRoot: true }];
+      while (stack.length > 0) {
+        const { node, isRoot } = stack.pop();
+        if (!node || typeof node.type !== "string") continue;
+        if (
+          !isRoot &&
+          stopAtLoopsAndFns &&
+          (LOOP_TYPES.has(node.type) || FUNCTION_TYPES.has(node.type))
+        ) {
+          continue;
+        }
+        if (predicate(node)) return true;
+        for (const key of visitorKeys[node.type] ?? []) {
+          const child = node[key];
+          if (Array.isArray(child)) {
+            for (const c of child) {
+              if (c) stack.push({ node: c, isRoot: false });
+            }
+          } else if (child && typeof child.type === "string") {
+            stack.push({ node: child, isRoot: false });
+          }
+        }
+      }
+      return false;
+    }
+
+    function checkLoop(node) {
+      if (!subtreeHas(node.body, isComposedSendWithRealSignal, true)) return;
+      const guardInTest = subtreeHas(node.test, isAbortGuard, false);
+      const guardInBody = subtreeHas(node.body, isAbortGuard, true);
+      if (guardInTest || guardInBody) return;
+      context.report({ node, messageId: "missingAbortPrecheck" });
+    }
+
+    return {
+      ForStatement: checkLoop,
+      ForOfStatement: checkLoop,
+      ForInStatement: checkLoop,
+      WhileStatement: checkLoop,
+      DoWhileStatement: checkLoop
+    };
+  }
+};

package/zod-companion-type.js

@@ -0,0 +1,159 @@
+/**
+ * ESLint Rule: zod-companion-type
+ *
+ * Catches the most common shape of Zod Pitfall 6 — `export const XSchema =
+ * z.<builder>(...)` where the schema name ends in `Schema` and the
+ * initializer is a direct `z.*` call — and requires a companion exported
+ * type with the matching name (e.g. `ComputeTypeSchema` → `ComputeType`).
+ * The companion may be:
+ *   1. `export type X = z.infer<typeof XSchema>` (the strongest form)
+ *   2. A re-export from a canonical source — `export { type X } from "..."`
+ *      or `export type { X } from "..."` — when the canonical type is
+ *      structurally derived from the same underlying constants the schema
+ *      consumes (e.g. `z.enum(COMPUTE_TYPES)` paired with
+ *      `type ComputeType = (typeof COMPUTE_TYPES)[number]` re-exported here).
+ *
+ * Intentional gaps in the catch surface (these forms bypass the rule and
+ * are NOT a bug — they are heuristic carve-outs to keep the rule low-noise):
+ *   - Helper-wrapped initializers — `export const FooSchema =
+ *     optionalOrDisabled(InnerSchema)` — the wrapper hides the `z.*` call.
+ *     If a companion type for these is needed, derive it manually with
+ *     `z.infer<typeof FooSchema>`; the rule won't enforce.
+ *   - Names that do not end in `Schema` — `export const
+ *     DatabaseGeneratorSchemaFromUI = z.object(...)` — by convention, the
+ *     `Schema` suffix marks "this is the type-bearing schema worth pairing
+ *     with a companion". Suffix-less exports are typically internal-shaped
+ *     or input-shaped and don't earn a companion.
+ *
+ * Without the companion, downstream consumers either widen to
+ * `string`/`unknown` (losing the brand) or duplicate the schema's regex/shape
+ *  — both reintroduce the schema-interface drift the schema was supposed to
+ * prevent.
+ *
+ * Codifies typescript-standards.md § "Pitfall 6: Exported Schema Without
+ * Companion z.infer Type" after 5 occurrences in 8 days (2026-04-21 to
+ * 2026-04-28: NetworkName, CidrString, ComputeType, VpcPeerAccepterOrchestratorSuccess
+ * structural-coupling sibling, InsightId).
+ */
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require companion type for every exported Zod schema (z.infer or re-export)",
+      category: "Best Practices",
+      recommended: true
+    },
+    messages: {
+      missingCompanionType:
+        "Exported Zod schema '{{schemaName}}' has no companion `export type {{typeName}}` in the same file. Add `export type {{typeName}} = z.infer<typeof {{schemaName}}>` or re-export the canonical type to prevent schema-interface drift."
+    },
+    schema: []
+  },
+
+  create(context) {
+    const exportedSchemas = new Map();
+    const exportedTypeNames = new Set();
+
+    function recordExportedTypeName(name) {
+      if (typeof name === "string" && name.length > 0) {
+        exportedTypeNames.add(name);
+      }
+    }
+
+    return {
+      ExportNamedDeclaration(node) {
+        if (node.declaration) {
+          if (node.declaration.type === "VariableDeclaration") {
+            for (const decl of node.declaration.declarations) {
+              if (decl.id.type !== "Identifier") continue;
+              const name = decl.id.name;
+              if (!name.endsWith("Schema")) continue;
+              if (!isZodSchemaInit(decl.init)) continue;
+              exportedSchemas.set(name, { node: decl.id });
+            }
+          }
+          if (node.declaration.type === "TSTypeAliasDeclaration") {
+            recordExportedTypeName(node.declaration.id.name);
+          }
+          if (node.declaration.type === "TSInterfaceDeclaration") {
+            recordExportedTypeName(node.declaration.id.name);
+          }
+        }
+
+        if (Array.isArray(node.specifiers)) {
+          const isTypeOnlyExport = node.exportKind === "type";
+          for (const spec of node.specifiers) {
+            if (spec.type !== "ExportSpecifier") continue;
+            if (isTypeOnlyExport || spec.exportKind === "type") {
+              const exported =
+                spec.exported.type === "Identifier"
+                  ? spec.exported.name
+                  : spec.exported.value;
+              recordExportedTypeName(exported);
+            }
+          }
+        }
+      },
+
+      "Program:exit"() {
+        if (exportedSchemas.size === 0) return;
+
+        const sourceText = context.sourceCode.getText();
+
+        for (const [schemaName, { node }] of exportedSchemas) {
+          const typeName = schemaName.replace(/Schema$/, "");
+
+          const inferPattern = new RegExp(
+            `z\\.infer\\s*<\\s*typeof\\s+${escapeRegex(schemaName)}\\s*>`
+          );
+          if (inferPattern.test(sourceText)) continue;
+
+          if (exportedTypeNames.has(typeName)) continue;
+
+          context.report({
+            node,
+            messageId: "missingCompanionType",
+            data: { schemaName, typeName }
+          });
+        }
+      }
+    };
+  }
+};
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function isZodSchemaInit(init) {
+  if (!init) return false;
+
+  let current = init;
+  while (current) {
+    if (current.type === "Identifier") {
+      // `*Schema.extend({...}).strict()` chains root at an imported schema.
+      return current.name === "z" || current.name.endsWith("Schema");
+    }
+    if (current.type === "MemberExpression") {
+      if (current.object.type === "Identifier") {
+        if (
+          current.object.name === "z" ||
+          current.object.name.endsWith("Schema")
+        ) {
+          return true;
+        }
+      }
+      current = current.object;
+      continue;
+    }
+    if (current.type === "CallExpression") {
+      current = current.callee;
+      continue;
+    }
+    return false;
+  }
+  return false;
+}

package/zod-strict-required.js

@@ -0,0 +1,153 @@
+/**
+ * ESLint Rule: zod-strict-required
+ *
+ * All z.object() schemas must use .strict() to reject unknown properties.
+ * Without .strict(), Zod silently strips unknown properties which can
+ * mask schema-interface drift bugs.
+ *
+ *  */
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require .strict() on all z.object() schemas",
+      category: "Best Practices",
+      recommended: true
+    },
+    messages: {
+      missingStrict:
+        "z.object() must use .strict() to reject unknown properties. Add .strict() after the object definition."
+    },
+    schema: [],
+    fixable: "code"
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        // Check for z.object(...) calls
+        if (!isZodObjectCall(node)) {
+          return;
+        }
+
+        // Check if this z.object() has .strict() chained
+        if (hasStrictChained(node)) {
+          return;
+        }
+
+        // Check if it's part of a chain that eventually has .strict()
+        if (isPartOfStrictChain(node)) {
+          return;
+        }
+
+        context.report({
+          node,
+          messageId: "missingStrict",
+          fix(fixer) {
+            // Find the end of the z.object({...}) call
+            const sourceCode = context.sourceCode;
+            const callEnd = node.range[1];
+
+            // Check what comes after - if it's a method chain, insert before the dot
+            const tokensAfter = sourceCode.getTokensAfter(node, { count: 1 });
+            if (tokensAfter.length > 0 && tokensAfter[0].value === ".") {
+              return fixer.insertTextAfter(node, ".strict()");
+            }
+
+            return fixer.insertTextAfterRange(
+              [callEnd - 1, callEnd],
+              ".strict()"
+            );
+          }
+        });
+      }
+    };
+  }
+};
+
+/**
+ * Check if a node is a z.object() call
+ */
+function isZodObjectCall(node) {
+  if (node.type !== "CallExpression") return false;
+
+  const callee = node.callee;
+
+  // z.object(...)
+  if (
+    callee.type === "MemberExpression" &&
+    callee.object.type === "Identifier" &&
+    callee.object.name === "z" &&
+    callee.property.type === "Identifier" &&
+    callee.property.name === "object"
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if node has .strict() directly chained
+ */
+function hasStrictChained(node) {
+  let parent = node.parent;
+
+  // Walk up the chain looking for .strict()
+  while (parent) {
+    if (
+      parent.type === "MemberExpression" &&
+      parent.property.type === "Identifier" &&
+      parent.property.name === "strict"
+    ) {
+      return true;
+    }
+
+    // If parent is a CallExpression, check its parent (for method chains)
+    if (parent.type === "CallExpression") {
+      parent = parent.parent;
+    } else if (parent.type === "MemberExpression") {
+      parent = parent.parent;
+    } else {
+      break;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if this z.object() is part of a larger chain that has .strict()
+ * e.g., z.object({...}).extend({...}).strict()
+ */
+function isPartOfStrictChain(node) {
+  // Start from the z.object() node and traverse up the entire chain
+  let current = node;
+
+  while (current.parent) {
+    const parent = current.parent;
+
+    // If we hit a MemberExpression accessing 'strict', we're good
+    if (
+      parent.type === "MemberExpression" &&
+      parent.property.type === "Identifier" &&
+      parent.property.name === "strict"
+    ) {
+      return true;
+    }
+
+    // Continue up through CallExpressions and MemberExpressions
+    if (
+      parent.type === "CallExpression" ||
+      parent.type === "MemberExpression"
+    ) {
+      current = parent;
+    } else {
+      break;
+    }
+  }
+
+  return false;
+}