@fjall/eslint-plugin 9.0.0 → 10.1.2

package/index.js

@@ -28,6 +28,7 @@ import noClassicConnectedAccountAssume from "./no-classic-connected-account-assu
 import noRawDbTransaction from "./no-raw-db-transaction.js";
 import noRawExitCode from "./no-raw-exit-code.js";
 import noReplacementStringExpansion from "./no-replacement-string-expansion.js";
+import noSilentResultDiscard from "./no-silent-result-discard.js";
 
 export default {
   rules: {
@@ -62,6 +63,7 @@ export default {
     "no-classic-connected-account-assume": noClassicConnectedAccountAssume,
     "no-raw-db-transaction": noRawDbTransaction,
     "no-raw-exit-code": noRawExitCode,
-    "no-replacement-string-expansion": noReplacementStringExpansion
+    "no-replacement-string-expansion": noReplacementStringExpansion,
+    "no-silent-result-discard": noSilentResultDiscard
   }
 };

package/no-silent-result-discard.js

@@ -0,0 +1,228 @@
+/**
+ * ESLint Rule: no-silent-result-discard
+ *
+ * A `Result` failure branch that neither propagates, throws, records, nor
+ * even reads the error silently conflates "could not read" with "empty" —
+ * the fail-open shape behind the secrets fail-open incident (a denied SSM
+ * read merged as an empty namespace level). Read-failure posture: value,
+ * creation and injection reads fail closed; availability-class reads may
+ * degrade only via an explicit, visible note; genuine absence is
+ * discriminated by error name (`errorType === "not_found"`,
+ * `isXNotFoundError`), never assumed from an undiscriminated failure.
+ *
+ * The rule flags only failure branches that are TRIVIALLY silent — every
+ * statement is a bare `continue`/`break`/`;` or a `return` of nothing/an
+ * empty literal (`null`, `undefined`, `[]`, `{}`, `""`, `false`, `0`,
+ * including TS-wrapped forms like `[] as T[]` and `void 0`), or the branch
+ * is empty. Any call, throw, `.error` read, or non-empty return in the
+ * branch counts as recording/propagating and passes, which keeps the
+ * false-positive rate near zero. A non-empty literal return
+ * (`return "unknown"`) is a semantic degraded verdict — the sanctioned
+ * degrade-with-visible-note pattern — and passes for the same reason.
+ *
+ * Known limitations (deliberate, matching the plugin's untyped design):
+ * - Discards routed through helper indirection
+ *   (`if (isFailure(x)) return handleQuietly(x)`) pass — any call counts.
+ * - `if (x.success) { ... }` with NO else (the drop-by-omission shape) is
+ *   not flagged; it is indistinguishable from optional enrichment without
+ *   type information.
+ * - A dropped return value of a Result-returning call needs parserServices
+ *   and is out of scope for this untyped rule.
+ * - Optional-chained tests (`x?.success`, either polarity) are skipped —
+ *   they double as null-guards.
+ * - Guard recognition is an exact-shape allowlist; unrecognised test shapes
+ *   pass unexamined — e.g. computed access (`result["success"]`), loose
+ *   equality, and `x.success !== false` as a positive guard (only
+ *   `x.success` / `isSuccess(x)` / `=== true` classify the else arm as the
+ *   failure branch).
+ *
+ * Escape hatch for genuine failure-means-absence sites:
+ * `// eslint-disable-next-line fjall/no-silent-result-discard -- <why>`
+ */
+
+/**
+ * `x.success` member read (non-computed, non-optional).
+ */
+function isSuccessMember(node) {
+  return (
+    node.type === "MemberExpression" &&
+    !node.computed &&
+    !node.optional &&
+    node.property.type === "Identifier" &&
+    node.property.name === "success"
+  );
+}
+
+/** `isFailure(x)` / `isSuccess(x)` helper call. */
+function isResultHelperCall(node, helperName) {
+  return (
+    node.type === "CallExpression" &&
+    node.callee.type === "Identifier" &&
+    node.callee.name === helperName &&
+    node.arguments.length === 1
+  );
+}
+
+/** `<lit> === x.success` / `x.success === <lit>` — returns the literal value. */
+function successComparisonLiteral(node, operator) {
+  if (node.type !== "BinaryExpression" || node.operator !== operator) {
+    return undefined;
+  }
+  const { left, right } = node;
+  if (isSuccessMember(left) && right.type === "Literal") return right.value;
+  if (isSuccessMember(right) && left.type === "Literal") return left.value;
+  return undefined;
+}
+
+/**
+ * Classify which arm of the IfStatement is the FAILURE branch.
+ * Returns "consequent", "alternate", or null when the test is not a
+ * recognised Result-success guard.
+ */
+function failureBranchOf(test) {
+  // !x.success / !isSuccess(x)
+  if (test.type === "UnaryExpression" && test.operator === "!") {
+    if (
+      isSuccessMember(test.argument) ||
+      isResultHelperCall(test.argument, "isSuccess")
+    ) {
+      return "consequent";
+    }
+    return null;
+  }
+  // isFailure(x)
+  if (isResultHelperCall(test, "isFailure")) return "consequent";
+  // x.success === false / false === x.success
+  if (successComparisonLiteral(test, "===") === false) return "consequent";
+  // x.success !== true / true !== x.success
+  if (successComparisonLiteral(test, "!==") === true) return "consequent";
+  // x.success / isSuccess(x) / x.success === true → failure arm is the else
+  if (
+    isSuccessMember(test) ||
+    isResultHelperCall(test, "isSuccess") ||
+    successComparisonLiteral(test, "===") === true
+  ) {
+    return "alternate";
+  }
+  return null;
+}
+
+/**
+ * Strip TS type-level wrappers (`as`, `satisfies`, `!`, `<T>`) and `void`
+ * so `return [] as T[]` / `return void 0` cannot evade the emptyish check.
+ * `void <call>` unwraps to the call, which is not emptyish, so a
+ * `return void logger.warn(...)` still counts as recording.
+ */
+function unwrapTypeExpressions(node) {
+  let current = node;
+  for (;;) {
+    if (
+      current.type === "TSAsExpression" ||
+      current.type === "TSSatisfiesExpression" ||
+      current.type === "TSNonNullExpression" ||
+      current.type === "TSTypeAssertion"
+    ) {
+      current = current.expression;
+    } else if (
+      current.type === "UnaryExpression" &&
+      current.operator === "void"
+    ) {
+      current = current.argument;
+    } else {
+      return current;
+    }
+  }
+}
+
+/**
+ * Nothing, or a silent-empty literal: null/undefined/""/0/false/[]/{}.
+ * A NON-empty literal (`return "unknown"`, `return "unprovable"`) is a
+ * semantic verdict — the degrade-with-visible-note pattern — and passes.
+ */
+function isEmptyishReturnArgument(rawArgument) {
+  if (!rawArgument) return true;
+  const argument = unwrapTypeExpressions(rawArgument);
+  if (argument.type === "Literal") {
+    return (
+      argument.value === null ||
+      argument.value === false ||
+      argument.value === 0 ||
+      argument.value === ""
+    );
+  }
+  if (argument.type === "Identifier" && argument.name === "undefined") {
+    return true;
+  }
+  if (
+    argument.type === "TemplateLiteral" &&
+    argument.expressions.length === 0
+  ) {
+    return true;
+  }
+  if (argument.type === "ArrayExpression" && argument.elements.length === 0) {
+    return true;
+  }
+  if (
+    argument.type === "ObjectExpression" &&
+    argument.properties.length === 0
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * True when the branch discards the failure without any trace: empty, or
+ * only bare continue/break/empty-ish returns. The statement whitelist
+ * structurally excludes calls, throws and `.error` reads, so any of those
+ * makes the branch pass.
+ */
+function isTriviallySilent(branch) {
+  const statements = branch.type === "BlockStatement" ? branch.body : [branch];
+  for (const statement of statements) {
+    if (statement.type === "ReturnStatement") {
+      if (!isEmptyishReturnArgument(statement.argument)) return false;
+    } else if (
+      statement.type !== "ContinueStatement" &&
+      statement.type !== "BreakStatement" &&
+      statement.type !== "EmptyStatement"
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow Result failure branches that silently discard the error",
+      category: "Best Practices",
+      recommended: true
+    },
+    messages: {
+      silentDiscard:
+        'This failure branch drops the Result error without a trace, conflating "could not read" with "empty". Propagate the failure, discriminate genuine absence by error name (errorType === "not_found" / isXNotFoundError), or record the degradation visibly (progress.warning / logger.warn). If failure genuinely means absence here, keep it with an eslint-disable comment and a -- justification (read-failure posture, robustness-standards).'
+    },
+    schema: []
+  },
+
+  create(context) {
+    return {
+      IfStatement(node) {
+        const arm = failureBranchOf(node.test);
+        if (arm === null) return;
+        const branch = arm === "consequent" ? node.consequent : node.alternate;
+        if (!branch) return;
+        // `else if` chains are their own IfStatement visit.
+        if (branch.type === "IfStatement") return;
+        if (isTriviallySilent(branch)) {
+          context.report({ node: branch, messageId: "silentDiscard" });
+        }
+      }
+    };
+  }
+};

package/package.json

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