@fjall/eslint-plugin 13.1.0 → 14.1.0

package/no-optional-warning-emission.js

@@ -8,32 +8,42 @@
  * a bound sink even when no surface registered a callback: absence of a
  * consumer means the spine's default sink, never silence.
  *
- * Sanctioned fixes (named in the report message):
- *   - `emitWarning(message, { scope })` (@fjall/util/diagnostics) wherever
- *     the CLI owns the terminal end of the lane — the always-spine route;
- *   - `emitStepWarnings(callbacks, step)` / `emitWarningEvent(callbacks,
- *     message, opts)` (deploy-core orchestration/contextHelpers) at the
- *     external-consumer boundary — present→callback, absent→spine.
+ * Exactly two warning conventions exist (diagnostics-spine design, routing
+ * rule), and both satisfy this rule structurally — no allowlist remains:
+ *   - Always-spine: `emitWarning(message, { scope })` (@fjall/util/
+ *     diagnostics) wherever the CLI owns the terminal end of the lane.
+ *   - External-boundary fallback: `emitWarningEvent`/`emitStepWarnings`
+ *     (deploy-core orchestration/contextHelpers), serving the out-of-repo
+ *     consumer of @fjall/deploy-core — present→callback, absent→spine. The
+ *     helper's shape (guard the callback, call it, fall through to
+ *     emitWarning) passes below precisely because its absent arm reaches
+ *     the spine; the boundary, correctly implemented, is not an instance
+ *     of the defect.
  *
- * Flagged shape: a callback invocation that can silently short-circuit (the
- * call itself is `?.()`, or any member link in its callee chain is optional)
- * whose callee names an `on[A-Z]`-shaped callback and whose arguments carry
- * an object literal with `type: "warning"` (TS `as`/`satisfies` wrappers
- * unwrapped, spread-extended literals included).
+ * Flagged shapes:
+ *   1. Optional-link emission: a callback invocation that can silently
+ *      short-circuit (the call itself is `?.()`, or any member link in its
+ *      callee chain is optional) whose callee names an `on[A-Z]`-shaped
+ *      callback and whose arguments carry an object literal with
+ *      `type: "warning"` (TS `as`/`satisfies` wrappers unwrapped,
+ *      spread-extended literals included). A bare-identifier callee also
+ *      counts as callback-named when its declaration initialiser reads an
+ *      `on[A-Z]` callback (`const cb = options.onProgress`) — the alias
+ *      does not launder the name.
+ *   2. Presence-guarded emission with no spine fallback: a PLAIN call of
+ *      the same shape whose availability is guarded by the surrounding code
+ *      (`if (cb) cb(…)`, `cb && cb(…)`, `cb ? cb(…) : …`, `typeof cb ===
+ *      "function"`, `!!cb`, `Boolean(cb)`, including a guard on the callee
+ *      chain's object) where the absent arm never reaches emitWarning/
+ *      emitWarningEvent/emitStepWarnings — no else/alternate spine call,
+ *      no fall-through spine call after the guard, no `||` spine
+ *      continuation. The same silent drop as shape 1, laundered through a
+ *      guard instead of `?.`.
  *
- * Deliberately kept wiring sites are declared in the rule-option allowlist
- * (`allow`), seeded from SANCTIONED_WARNING_EMISSION_SITES below — enumerated
- * config data, reviewable in one place, in preference to inline disables.
- * Each entry names a file (path-suffix match on a path boundary) and
- * optionally narrows by:
- *   - `enclosingFunction` — the nearest NAMED enclosing function; property-
- *     assigned and variable-assigned arrows count as named, anonymous
- *     wrappers (returned arrows, IIFEs) are skipped upward;
- *   - `withinCallee` — the site sits inside an ARGUMENT of a call or `new`
- *     of this name (callee identifier, or member property for method calls);
- *   - `messageProperty` — the event literal's `message` value is a read of
- *     this property (or a bare identifier of this name).
- * All fields given on an entry must match for the entry to sanction a site.
+ * Both shapes see through the `.call`/`.apply` spellings: the invoked
+ * function is the member one link up (`options.onProgress.call(…)` reads
+ * as onProgress; `emitWarning.call(…)` still counts as the spine), and an
+ * `.apply` argument array is scanned for the warning literal.
  *
  * Known limitations (deliberate, matching the plugin's untyped design):
  * - Literal-keyed only: an event object built in a binding and passed
@@ -44,197 +54,42 @@
  *   the rule cannot tell the two onWarning arities apart.
  * - Non-callback-named emitters (`emit?.({ type: "warning" })`) pass — the
  *   spine's own sink plumbing legitimately holds that shape.
+ * - Guard analysis is intra-function: a guarded emission deferred into a
+ *   nested closure, and the inverted early-exit guard (`if (!cb) return;
+ *   cb(…)`), pass unexamined.
+ * - Alias resolution reads declaration initialisers only: a callback
+ *   assigned to a pre-declared binding after the fact (`let cb; cb =
+ *   options.onProgress;`) passes unexamined. `.bind` aliases (`const cb =
+ *   options.onProgress?.bind(x)`) pass too — the initialiser is a call
+ *   result, which alias resolution does not follow.
+ * - A guard hoisted into a boolean binding (`const hasCb =
+ *   !!options.onProgress; if (hasCb) options.onProgress(…)`) passes
+ *   unexamined — the guard's key no longer names the callee chain.
+ * - Absent-path reachability treats a nested function as reachable only
+ *   from an invoked position (IIFE callee or call argument): a spine call
+ *   inside a merely-declared closure does not satisfy the fallback, and
+ *   conversely a fallback wrapped deeper (e.g. a closure stored in an
+ *   object property handed to a runner) is not credited — that shape flags
+ *   and needs the direct spelling or a disable comment.
  *
- * Escape hatch: prefer an `allow` entry so the sanctioned set stays
- * enumerable; `// eslint-disable-next-line fjall/no-optional-warning-emission
- * -- <why>` remains available for genuinely local one-offs.
+ * Escape hatch: `// eslint-disable-next-line
+ * fjall/no-optional-warning-emission -- <why>` for genuinely local
+ * one-offs; there is no allow option.
  */
 
 const CALLBACK_RE = /^on[A-Z]/;
 
 /**
- * The sanctioned optional-warning wiring sites (diagnostics-spine design,
- * Component 8). Imported by cli/eslint.config.js and the root
- * eslint.config.mjs as the shared `allow` seed — single source, so the two
- * configs cannot drift.
+ * Callees whose invocation counts as reaching the diagnostics spine on the
+ * absent-callback path: the always-spine emitter and the two
+ * external-boundary fallback helpers (which themselves fall back to
+ * emitWarning when no callback is wired).
  */
-export const SANCTIONED_WARNING_EMISSION_SITES = [
-  // Attribution-degrade warning: emits into the caller-supplied onProgress
-  // by contract (the caller decided the surface before invoking).
-  {
-    file: "cli/src/services/deployment/deploymentApiHelpers.ts",
-    enclosingFunction: "warnUnattributedOperation"
-  },
-  // §5.5 gateUntrackedDeploy onWarning wiring — feeds the tracked-deploy
-  // policy gate, whose warn-and-proceed arm renders on the caller's surface.
-  {
-    file: "cli/src/services/deployment/applicationDeployment.ts",
-    withinCallee: "gateUntrackedDeploy"
-  },
-  // §5.6 accept-and-mark upgrade notice off the 201 — a single non-blocking
-  // per-deploy notice on the deploy surface's own warning arm.
-  {
-    file: "cli/src/services/deployment/applicationDeployment.ts",
-    enclosingFunction: "deployApplication",
-    messageProperty: "upgradeNotice"
-  },
-  // The spine helpers' own internals: their present→callback arm IS the
-  // external-boundary fallback contract the rule points everyone else at.
-  {
-    file: "deploy-core/src/orchestration/contextHelpers.ts",
-    enclosingFunction: "emitWarningEvent"
-  },
-  {
-    file: "deploy-core/src/orchestration/contextHelpers.ts",
-    enclosingFunction: "emitStepWarnings"
-  },
-  {
-    file: "cli/src/services/deployment/callbackShared.ts",
-    enclosingFunction: "createOnLogHandler"
-  },
-
-  // Direct-producer lane — live-rendered via the surface builders' wired
-  // onProgress; migrates in the direct-producer-migration follow-on.
-  {
-    file: "cli/src/services/deployment/applicationDeployment.ts",
-    enclosingFunction: "warnBestEffort"
-  },
-  {
-    file: "cli/src/services/deployment/applicationDeployment.ts",
-    enclosingFunction: "deployApplication"
-  },
-  // DeploymentTracker onWarning wiring arrow.
-  {
-    file: "cli/src/services/deployment/applicationDeployment.ts",
-    enclosingFunction: "onWarning"
-  },
-  {
-    file: "cli/src/services/deployment/applicationDestruction.ts",
-    enclosingFunction: "destroyApplication"
-  },
-  {
-    file: "cli/src/services/deployment/applicationDestruction.ts",
-    enclosingFunction: "onWarning"
-  },
-  {
-    file: "cli/src/services/deployment/applicationDestruction.ts",
-    enclosingFunction: "trackAndReturnFailure"
-  },
-  {
-    file: "cli/src/services/deployment/applicationRestart.ts",
-    enclosingFunction: "warnBestEffort"
-  },
-  {
-    file: "cli/src/services/deployment/applicationRestart.ts",
-    enclosingFunction: "onWarning"
-  },
-  // Quarantine/retained-bucket cleanup signals on both adapter copies.
-  {
-    file: "cli/src/services/deployment/baseCallbackBuilder.ts",
-    enclosingFunction: "onStackCleanupProgress"
-  },
-  {
-    file: "cli/src/services/deployment/InteractiveCallbackAdapter.ts",
-    enclosingFunction: "onStackCleanupProgress"
-  },
-  {
-    file: "cli/src/services/deployment/orgCallbackMapper.ts",
-    enclosingFunction: "onCascadeLedger"
-  },
-
-  // Import lane — importOperation wires onProgress on every production
-  // path; deliberately callback-based, revisited in the
-  // direct-producer-migration follow-on.
-  {
-    file: "cli/src/services/import/ImportService.ts",
-    enclosingFunction: "importResource"
-  },
-  {
-    file: "cli/src/services/import/importAdoptionHelpers.ts",
-    enclosingFunction: "generateAndWriteCode"
-  },
-  {
-    file: "cli/src/services/monitoring/DiscoveryService.ts",
-    enclosingFunction: "readS3BucketDetail"
-  },
-  {
-    file: "cli/src/services/monitoring/DiscoveryService.ts",
-    enclosingFunction: "discoverVpcs"
-  },
-
-  // Pre-existing stock, wiring unverified — catalogued as fresh census
-  // input for the follow-on census (ADR); audited then migrated in the
-  // direct-producer-migration follow-on.
-  {
-    file: "cli/src/commands/provisioning/restore.ts",
-    enclosingFunction: "onWarning"
-  },
-  {
-    file: "cli/src/operations/resources/secretsOperations.ts",
-    enclosingFunction: "applyDeclaration"
-  },
-  {
-    file: "cli/src/services/application/ApplicationDetectionHelpers.ts",
-    enclosingFunction: "reportValidationNotRun"
-  },
-  {
-    file: "cli/src/services/application/ApplicationDetectionHelpers.ts",
-    enclosingFunction: "validateSecrets"
-  },
-  {
-    file: "cli/src/services/auth/OidcBootstrapService.ts",
-    enclosingFunction: "establishOidcTrust"
-  },
-  {
-    file: "cli/src/services/aws-account/AwsAccountService.ts",
-    enclosingFunction: "buildProviderAccountsFromConfig"
-  },
-  {
-    file: "cli/src/services/aws/awsExecution.ts",
-    enclosingFunction: "executeWithAwsCredentials"
-  },
-  {
-    file: "cli/src/services/domain-dns/CliDomainDeployProvider.ts",
-    enclosingFunction: "deployDomain"
-  },
-  {
-    file: "cli/src/services/domain-dns/delegationService.ts",
-    enclosingFunction: "deployPhase"
-  },
-  {
-    file: "cli/src/services/organisation/OrganisationDeployService.ts",
-    enclosingFunction: "onWarn"
-  },
-  {
-    file: "cli/src/services/organisation/OrganisationDestroyService.ts",
-    enclosingFunction: "onWarning"
-  },
-  {
-    file: "cli/src/services/organisation/OrganisationDestroyService.ts",
-    enclosingFunction: "destroy"
-  },
-  {
-    file: "cli/src/services/organisation/OrganisationSetupService.ts",
-    enclosingFunction: "onWarning"
-  },
-  {
-    file: "cli/src/services/organisation/OrganisationSetupService.ts",
-    enclosingFunction: "runOrganisationSetup"
-  },
-  {
-    file: "cli/src/services/organisation/OrganisationStandaloneHelpers.ts",
-    enclosingFunction: "registerStandaloneAccount"
-  },
-
-  // Dormant reporter-warning twin: ProgressReporter.warning has no live
-  // production instantiation post-tap; kept until the reporter-lane-reroute
-  // follow-on (a diagnostics import into the types module would be wrong
-  // layering).
-  {
-    file: "deploy-core/src/types/ProgressEvent.ts",
-    enclosingFunction: "warning"
-  }
-];
+const SPINE_CALLEES = new Set([
+  "emitWarning",
+  "emitWarningEvent",
+  "emitStepWarnings"
+]);
 
 /**
  * Strip TS type-level wrappers so `"warning" as const` and
@@ -246,7 +101,8 @@ function unwrapTypeExpressions(node) {
     current.type === "TSAsExpression" ||
     current.type === "TSSatisfiesExpression" ||
     current.type === "TSNonNullExpression" ||
-    current.type === "TSTypeAssertion"
+    current.type === "TSTypeAssertion" ||
+    current.type === "ChainExpression"
   ) {
     current = current.expression;
   }
@@ -269,7 +125,12 @@ function invocationCanSilentlySkip(node) {
   return false;
 }
 
-/** Terminal callee name: bare identifier, or member property. */
+/**
+ * Terminal callee name: bare identifier, or member property. The
+ * `.call`/`.apply` spellings invoke their OBJECT, so they are named one
+ * link up when the object has a stable name (falling back to the literal
+ * property name when it does not).
+ */
 function terminalCalleeName(callee) {
   let current = callee;
   if (current.type === "ChainExpression") current = current.expression;
@@ -279,6 +140,10 @@ function terminalCalleeName(callee) {
     !current.computed &&
     current.property.type === "Identifier"
   ) {
+    if (current.property.name === "call" || current.property.name === "apply") {
+      const objectName = terminalCalleeName(current.object);
+      if (objectName !== null) return objectName;
+    }
     return current.property.name;
   }
   return null;
@@ -292,18 +157,44 @@ function isPropertyNamed(property, name) {
   return false;
 }
 
+/** Object literal carrying `type: "warning"`? */
+function isWarningEventLiteral(argument) {
+  if (argument.type !== "ObjectExpression") return false;
+  for (const property of argument.properties) {
+    if (!isPropertyNamed(property, "type")) continue;
+    const value = unwrapTypeExpressions(property.value);
+    if (value.type === "Literal" && value.value === "warning") {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** True when the call is spelled through `.apply` (array-of-args form). */
+function isApplySpelling(callee) {
+  let current = callee;
+  if (current.type === "ChainExpression") current = current.expression;
+  return (
+    current.type === "MemberExpression" &&
+    !current.computed &&
+    current.property.type === "Identifier" &&
+    current.property.name === "apply"
+  );
+}
+
 /**
- * First argument object literal carrying `type: "warning"`, else null.
+ * First argument object literal carrying `type: "warning"`, else null. For
+ * the `.apply` spelling the argument array's elements are scanned too.
  */
 function findWarningEventLiteral(node) {
   for (const rawArgument of node.arguments) {
     const argument = unwrapTypeExpressions(rawArgument);
-    if (argument.type !== "ObjectExpression") continue;
-    for (const property of argument.properties) {
-      if (!isPropertyNamed(property, "type")) continue;
-      const value = unwrapTypeExpressions(property.value);
-      if (value.type === "Literal" && value.value === "warning") {
-        return argument;
+    if (isWarningEventLiteral(argument)) return argument;
+    if (argument.type === "ArrayExpression" && isApplySpelling(node.callee)) {
+      for (const rawElement of argument.elements) {
+        if (rawElement === null) continue;
+        const element = unwrapTypeExpressions(rawElement);
+        if (isWarningEventLiteral(element)) return element;
       }
     }
   }
@@ -311,145 +202,321 @@ function findWarningEventLiteral(node) {
 }
 
 /**
- * Name of a function node, when one is derivable: own id, variable binding,
- * object-property key, class-method key, or assignment target.
+ * True when a bare-identifier callee aliases an `on[A-Z]`-named callback:
+ * its resolved declaration's initialiser is (a member read of) a
+ * callback-named expression — `const cb = options.onProgress` /
+ * `= callbacks?.onProgress` / `= onProgress`. Declaration initialisers
+ * only; later reassignment is a documented pass.
  */
-function functionName(fn) {
-  if (
-    (fn.type === "FunctionDeclaration" || fn.type === "FunctionExpression") &&
-    fn.id
-  ) {
-    return fn.id.name;
+function aliasesCallbackName(callee, sourceCode) {
+  let calleeNode = callee;
+  if (calleeNode.type === "ChainExpression") {
+    calleeNode = calleeNode.expression;
   }
-  const parent = fn.parent;
-  if (!parent) return null;
+  // `cb.call(…)`/`cb.apply(…)` invoke the alias one link up.
   if (
-    parent.type === "VariableDeclarator" &&
-    parent.init === fn &&
-    parent.id.type === "Identifier"
+    calleeNode.type === "MemberExpression" &&
+    !calleeNode.computed &&
+    calleeNode.property.type === "Identifier" &&
+    (calleeNode.property.name === "call" ||
+      calleeNode.property.name === "apply")
   ) {
-    return parent.id.name;
+    calleeNode = calleeNode.object;
   }
-  if (parent.type === "Property" && parent.value === fn && !parent.computed) {
-    if (parent.key.type === "Identifier") return parent.key.name;
-    if (parent.key.type === "Literal" && typeof parent.key.value === "string") {
-      return parent.key.value;
-    }
+  if (calleeNode.type !== "Identifier") return false;
+
+  let scope = sourceCode.getScope(calleeNode);
+  let variable = null;
+  while (scope !== null && variable === null) {
+    variable = scope.variables.find((v) => v.name === calleeNode.name) ?? null;
+    scope = scope.upper;
   }
+  if (variable === null) return false;
+
+  for (const def of variable.defs) {
+    if (def.type !== "Variable" || def.node.init === null) continue;
+    const init = unwrapTypeExpressions(def.node.init);
+    const initName = terminalCalleeName(init);
+    if (initName !== null && CALLBACK_RE.test(initName)) return true;
+  }
+  return false;
+}
+
+/** Function-node predicate shared by the guard and reachability walks. */
+function isFunctionNode(node) {
+  return (
+    node.type === "FunctionDeclaration" ||
+    node.type === "FunctionExpression" ||
+    node.type === "ArrowFunctionExpression"
+  );
+}
+
+/**
+ * Canonical spelling of a presence-testable expression: an identifier,
+ * `this`, or a non-computed member chain over those. Optional links and TS
+ * wrappers are normalised away, so `callbacks?.onProgress` and
+ * `callbacks.onProgress` share a key. Null when the expression has no
+ * stable spelling (computed member, call result, …).
+ */
+function expressionKey(node) {
+  const current = unwrapTypeExpressions(node);
+  if (current.type === "Identifier") return current.name;
+  if (current.type === "ThisExpression") return "this";
   if (
-    parent.type === "MethodDefinition" &&
-    parent.value === fn &&
-    !parent.computed &&
-    parent.key.type === "Identifier"
+    current.type === "MemberExpression" &&
+    !current.computed &&
+    current.property.type === "Identifier"
   ) {
-    return parent.key.name;
-  }
-  if (parent.type === "AssignmentExpression" && parent.right === fn) {
-    if (parent.left.type === "Identifier") return parent.left.name;
-    if (
-      parent.left.type === "MemberExpression" &&
-      !parent.left.computed &&
-      parent.left.property.type === "Identifier"
-    ) {
-      return parent.left.property.name;
-    }
+    const objectKey = expressionKey(current.object);
+    return objectKey === null ? null : `${objectKey}.${current.property.name}`;
   }
   return null;
 }
 
 /**
- * Nearest NAMED enclosing function: anonymous wrappers are skipped upward so
- * a returned arrow attributes to the factory that returns it, while a
- * property-assigned arrow (`onWarning: (m) => …`) attributes to its key.
+ * True when establishing `guardKey` present also establishes the call path
+ * to `calleeKey`: the same expression, or a prefix of its member chain
+ * (guarding `callbacks` guards `callbacks.onProgress`).
  */
-function nearestNamedEnclosingFunction(node) {
-  let current = node.parent;
-  while (current) {
-    if (
-      current.type === "FunctionDeclaration" ||
-      current.type === "FunctionExpression" ||
-      current.type === "ArrowFunctionExpression"
-    ) {
-      const name = functionName(current);
-      if (name !== null) return name;
-    }
-    current = current.parent;
+function keyGuardsCallee(guardKey, calleeKey) {
+  if (guardKey === null) return false;
+  return calleeKey === guardKey || calleeKey.startsWith(`${guardKey}.`);
+}
+
+/** `undefined`, `null`, or `void …` — the absence spellings in guards. */
+function isUndefinedLike(node) {
+  const value = unwrapTypeExpressions(node);
+  if (value.type === "Identifier" && value.name === "undefined") return true;
+  if (value.type === "Literal" && value.value === null) return true;
+  if (value.type === "UnaryExpression" && value.operator === "void") {
+    return true;
   }
-  return null;
+  return false;
 }
 
 /**
- * True when `node` sits inside an ARGUMENT of a call/new whose callee spells
- * `calleeName`. Walks the full ancestor chain — the wiring arrow between the
- * emission and the sanctioning call is expected.
+ * True when one side of `binary` is `typeof <expr guarding calleeKey>` and
+ * the other is the string literal `literalValue`.
  */
-function isWithinCalleeArgument(node, calleeName) {
-  let previous = node;
-  let current = node.parent;
-  while (current) {
+function typeofComparedTo(binary, calleeKey, literalValue) {
+  const sides = [
+    [binary.left, binary.right],
+    [binary.right, binary.left]
+  ];
+  for (const [candidate, literal] of sides) {
+    const typeofSide = unwrapTypeExpressions(candidate);
+    const literalSide = unwrapTypeExpressions(literal);
     if (
-      (current.type === "CallExpression" || current.type === "NewExpression") &&
-      previous !== current.callee &&
-      terminalCalleeName(current.callee) === calleeName
+      typeofSide.type === "UnaryExpression" &&
+      typeofSide.operator === "typeof" &&
+      keyGuardsCallee(expressionKey(typeofSide.argument), calleeKey) &&
+      literalSide.type === "Literal" &&
+      literalSide.value === literalValue
     ) {
       return true;
     }
-    previous = current;
-    current = current.parent;
   }
   return false;
 }
 
 /**
- * True when the event literal's `message` value reads `propertyName` — a
- * non-computed member access (`startOutcome.upgradeNotice`) or a bare
- * identifier of that name.
+ * True when `test` (or an `&&`-conjunct of it) establishes that the callee
+ * spelled `calleeKey` is present/callable: bare truthiness, `!!` double
+ * negation, `Boolean(…)`, `!== undefined` / `!= null`, `typeof … !==
+ * "undefined"`, or `typeof … === "function"` — over the callee expression
+ * itself or a prefix of its member chain.
  */
-function messageReadsProperty(eventLiteral, propertyName) {
-  for (const property of eventLiteral.properties) {
-    if (!isPropertyNamed(property, "message")) continue;
-    const value = unwrapTypeExpressions(property.value);
-    if (value.type === "Identifier") return value.name === propertyName;
-    if (
-      value.type === "MemberExpression" &&
-      !value.computed &&
-      value.property.type === "Identifier"
-    ) {
-      return value.property.name === propertyName;
+function testGuardsPresence(test, calleeKey) {
+  const condition = unwrapTypeExpressions(test);
+  if (condition.type === "LogicalExpression" && condition.operator === "&&") {
+    return (
+      testGuardsPresence(condition.left, calleeKey) ||
+      testGuardsPresence(condition.right, calleeKey)
+    );
+  }
+  if (condition.type === "UnaryExpression" && condition.operator === "!") {
+    const inner = unwrapTypeExpressions(condition.argument);
+    return (
+      inner.type === "UnaryExpression" &&
+      inner.operator === "!" &&
+      testGuardsPresence(inner.argument, calleeKey)
+    );
+  }
+  if (
+    condition.type === "CallExpression" &&
+    condition.callee.type === "Identifier" &&
+    condition.callee.name === "Boolean" &&
+    condition.arguments.length === 1
+  ) {
+    return testGuardsPresence(condition.arguments[0], calleeKey);
+  }
+  if (keyGuardsCallee(expressionKey(condition), calleeKey)) return true;
+  if (condition.type === "BinaryExpression") {
+    const { operator } = condition;
+    if (operator === "!==" || operator === "!=") {
+      if (
+        (isUndefinedLike(condition.right) &&
+          keyGuardsCallee(expressionKey(condition.left), calleeKey)) ||
+        (isUndefinedLike(condition.left) &&
+          keyGuardsCallee(expressionKey(condition.right), calleeKey))
+      ) {
+        return true;
+      }
+      if (typeofComparedTo(condition, calleeKey, "undefined")) return true;
+    }
+    if (operator === "===" || operator === "==") {
+      if (typeofComparedTo(condition, calleeKey, "function")) return true;
     }
   }
   return false;
 }
 
-/** Path-suffix match on a path boundary (or exact match). */
-function fileMatches(filename, entryFile) {
-  const normalised = filename.replace(/\\/g, "/");
-  return normalised === entryFile || normalised.endsWith(`/${entryFile}`);
-}
-
-function siteIsSanctioned(allow, filename, node, eventLiteral) {
-  for (const entry of allow) {
-    if (!fileMatches(filename, entry.file)) continue;
+/**
+ * Innermost construct that presence-guards `calleeKey` around `node`: an
+ * IfStatement/ConditionalExpression whose test guards the callee with the
+ * node in its consequent, or a `&&` whose left guards it with the node on
+ * the right. Intra-function — the walk stops at the enclosing function
+ * boundary (a guarded emission deferred into a nested closure is a
+ * documented pass).
+ */
+function findPresenceGuard(node, calleeKey) {
+  let previous = node;
+  let current = node.parent;
+  while (current && !isFunctionNode(current)) {
     if (
-      entry.enclosingFunction !== undefined &&
-      nearestNamedEnclosingFunction(node) !== entry.enclosingFunction
+      current.type === "IfStatement" &&
+      previous === current.consequent &&
+      testGuardsPresence(current.test, calleeKey)
     ) {
-      continue;
+      return current;
     }
     if (
-      entry.withinCallee !== undefined &&
-      !isWithinCalleeArgument(node, entry.withinCallee)
+      current.type === "ConditionalExpression" &&
+      previous === current.consequent &&
+      testGuardsPresence(current.test, calleeKey)
     ) {
-      continue;
+      return current;
     }
     if (
-      entry.messageProperty !== undefined &&
-      !messageReadsProperty(eventLiteral, entry.messageProperty)
+      current.type === "LogicalExpression" &&
+      current.operator === "&&" &&
+      previous === current.right &&
+      testGuardsPresence(current.left, calleeKey)
     ) {
-      continue;
+      return current;
     }
+    previous = current;
+    current = current.parent;
+  }
+  return null;
+}
+
+/**
+ * True when a function-valued child sits in a position that invokes it (or
+ * hands it to something that may): the callee of a call (IIFE) or a call
+ * argument (callback given to a runner). A function value anywhere else — a
+ * declaration, a variable initialiser, an else-arm closure — executes
+ * nothing where it stands, so a spine call inside it must not count as the
+ * absent path reaching the spine.
+ */
+function functionChildMayRun(parent, child) {
+  return (
+    parent.type === "CallExpression" &&
+    (parent.callee === child || parent.arguments.includes(child))
+  );
+}
+
+/**
+ * True when `node`'s subtree contains a REACHABLE call to a spine callee.
+ * Recursive descent over AST children; never follows `parent` links.
+ * Nested function bodies are descended only from an invoked position
+ * (see functionChildMayRun) — a merely-declared closure mentioning
+ * emitWarning reaches nothing at runtime.
+ */
+function containsSpineCall(node) {
+  if (
+    node.type === "CallExpression" &&
+    SPINE_CALLEES.has(terminalCalleeName(node.callee) ?? "")
+  ) {
+    return true;
+  }
+  for (const key of Object.keys(node)) {
+    if (key === "parent") continue;
+    const value = node[key];
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (
+          child !== null &&
+          typeof child === "object" &&
+          typeof child.type === "string" &&
+          (!isFunctionNode(child) || functionChildMayRun(node, child)) &&
+          containsSpineCall(child)
+        ) {
+          return true;
+        }
+      }
+    } else if (
+      value !== null &&
+      typeof value === "object" &&
+      typeof value.type === "string" &&
+      (!isFunctionNode(value) || functionChildMayRun(node, value)) &&
+      containsSpineCall(value)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * True when the absent-callback path of `guard` can still reach the spine:
+ * the guard's own alternate branch carries a spine call, a statement after
+ * the guard (walking enclosing blocks up to the function boundary) does —
+ * the boundary-helper shape guards, calls, returns, and falls through to
+ * emitWarning — or a `||` continuation to the guard's right does.
+ * Errs towards passing: partial reachability on exotic control flow is
+ * accepted rather than over-flagged.
+ */
+function absentPathReachesSpine(guard) {
+  if (
+    guard.type === "IfStatement" &&
+    guard.alternate !== null &&
+    containsSpineCall(guard.alternate)
+  ) {
+    return true;
+  }
+  if (
+    guard.type === "ConditionalExpression" &&
+    containsSpineCall(guard.alternate)
+  ) {
     return true;
   }
+
+  let previous = guard;
+  let current = guard.parent;
+  while (current && !isFunctionNode(current)) {
+    const body =
+      current.type === "BlockStatement" || current.type === "Program"
+        ? current.body
+        : current.type === "SwitchCase"
+          ? current.consequent
+          : null;
+    if (body !== null) {
+      const index = body.indexOf(previous);
+      for (let i = index + 1; i < body.length; i++) {
+        if (containsSpineCall(body[i])) return true;
+      }
+    } else if (
+      current.type === "LogicalExpression" &&
+      current.operator === "||" &&
+      previous === current.left &&
+      containsSpineCall(current.right)
+    ) {
+      return true;
+    }
+    previous = current;
+    current = current.parent;
+  }
   return false;
 }
 
@@ -459,58 +526,55 @@ export default {
     type: "problem",
     docs: {
       description:
-        "Disallow warning-typed events on optional callback links — an absent link silently swallows the warning; route it via the diagnostics spine",
+        "Disallow warning-typed events on optional or presence-guarded callback links with no spine fallback — an absent link silently swallows the warning; route it via the diagnostics spine",
       category: "Possible Errors",
       recommended: true
     },
     messages: {
       optionalWarningEmission:
-        "Warning-typed event rides an optional callback link (`{{callee}}`) — when the link is absent the warning vanishes silently. Emit via emitWarning(message, { scope }) (@fjall/util/diagnostics) where the CLI owns the lane, or emitStepWarnings/emitWarningEvent (deploy-core contextHelpers) at the external-consumer boundary. Deliberately kept wiring sites belong in this rule's `allow` option, not behind inline disables."
+        "Warning-typed event rides an optional callback link (`{{callee}}`) — when the link is absent the warning vanishes silently. Emit via emitWarning(message, { scope }) (@fjall/util/diagnostics) where the CLI owns the lane, or emitStepWarnings/emitWarningEvent (deploy-core contextHelpers) at the external-consumer boundary.",
+      guardedWarningEmission:
+        "Warning-typed event rides a presence-guarded callback (`{{callee}}`) whose absent arm never reaches the diagnostics spine — when the callback is absent the warning vanishes silently. Emit via emitWarning(message, { scope }) (@fjall/util/diagnostics) where the CLI owns the lane, or give the absent arm the external-boundary fallback shape (present→callback, absent→emitWarning; see deploy-core contextHelpers emitWarningEvent)."
     },
-    schema: [
-      {
-        type: "object",
-        properties: {
-          allow: {
-            type: "array",
-            items: {
-              type: "object",
-              properties: {
-                file: { type: "string" },
-                enclosingFunction: { type: "string" },
-                withinCallee: { type: "string" },
-                messageProperty: { type: "string" }
-              },
-              required: ["file"],
-              additionalProperties: false
-            }
-          }
-        },
-        additionalProperties: false
-      }
-    ]
+    schema: []
   },
 
   create(context) {
-    const allow = context.options[0]?.allow ?? [];
-
     return {
       CallExpression(node) {
-        if (!invocationCanSilentlySkip(node)) return;
-
         const calleeName = terminalCalleeName(node.callee);
-        if (calleeName === null || !CALLBACK_RE.test(calleeName)) return;
+        if (calleeName === null) return;
+        if (
+          !CALLBACK_RE.test(calleeName) &&
+          !aliasesCallbackName(node.callee, context.sourceCode)
+        ) {
+          return;
+        }
 
         const eventLiteral = findWarningEventLiteral(node);
         if (eventLiteral === null) return;
 
-        if (siteIsSanctioned(allow, context.filename, node, eventLiteral)) {
+        if (invocationCanSilentlySkip(node)) {
+          context.report({
+            node,
+            messageId: "optionalWarningEmission",
+            data: { callee: calleeName }
+          });
           return;
         }
 
+        // Hardening: a plain call laundered through a presence guard drops
+        // the warning just as silently when the absent arm has no spine
+        // fallback.
+        const calleeKey = expressionKey(node.callee);
+        if (calleeKey === null) return;
+        const guard = findPresenceGuard(node, calleeKey);
+        if (guard === null) return;
+        if (absentPathReachesSpine(guard)) return;
+
         context.report({
           node,
-          messageId: "optionalWarningEmission",
+          messageId: "guardedWarningEmission",
           data: { callee: calleeName }
         });
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/eslint-plugin",
-  "version": "13.1.0",
+  "version": "14.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",