@onrails/eslint-plugin 0.1.4 → 0.2.0

package/README.md

@@ -50,6 +50,7 @@ export default [
 | `@onrails/no-unsafe-unwrap` | Flags `_unsafeUnwrap*` outside test files |
 | `@onrails/no-deprecated-synonyms` | Flags deprecated synonyms (`chain`, `fold`, `getOrElse`, `of`, …) and suggests the canonical names |
 | `@onrails/fluent-stays-local` | Flags `FluentResult`/`FluentMaybe` escaping as a return type, an exported binding, a stored field, or a serialize/postMessage/cache argument |
+| `@onrails/carrier-sinks-need-from` | Flags `JSON.parse` / `structuredClone` / `.json()` output typed as `Result` / `Maybe` without `Result.from` / `Maybe.from` (plain data has no methods) |
 
 ## Caveats (v0)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onrails/eslint-plugin",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "ESLint rules for @onrails/result boundaries — flags Promise<Result<…>> in public APIs and _unsafeUnwrap*. Replaces unmaintained eslint-plugin-neverthrow.",
   "license": "MIT",
   "author": "Alan R. Soares",
@@ -41,7 +41,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "eslint": "^10.4.0"
+    "eslint": "^10.8.1"
   },
   "peerDependenciesMeta": {
     "@typescript-eslint/parser": {
@@ -54,7 +54,8 @@
     "check": "bun run typecheck && bun test"
   },
   "devDependencies": {
-    "@typescript-eslint/parser": "^8.60.0",
-    "eslint": "^10.4.0"
+    "@typescript-eslint/parser": "^8.67.0",
+    "eslint": "^10.8.1",
+    "typescript": "^6.0.3"
   }
 }

package/src/index.js

@@ -348,6 +348,220 @@ const fluentStaysLocal = {
   },
 };
 
+/**
+ * Carrier types and deserialization sinks. Hand-copied from `@onrails/codemod`
+ * `src/boundary-spec.ts` (cross-package imports forbidden);
+ * `packages/codemod/test/boundary-conformance.spec.ts` keeps copies in sync.
+ */
+const CARRIER_TYPES = new Set(["Result", "Maybe"]);
+const CARRIER_SINKS = new Set(["JSON.parse", "structuredClone"]);
+const CARRIER_SINK_METHODS = new Set(["json"]);
+
+/**
+ * Loose expression shape for the sink walk (`await`, `as`, parens, calls).
+ *
+ * @typedef {object} LooseExpr
+ * @property {string} type
+ * @property {string} [name]
+ * @property {LooseExpr} [argument]
+ * @property {LooseExpr} [expression]
+ * @property {LooseExpr} [callee]
+ * @property {LooseExpr} [object]
+ * @property {LooseExpr} [property]
+ * @property {LooseExpr} [typeAnnotation]
+ * @property {LooseExpr} [typeName]
+ */
+
+/**
+ * True when the expression is a deserialization sink call, looking through
+ * `await` and `as` wrappers: `JSON.parse(x)`, `structuredClone(x)`, `res.json()`.
+ *
+ * @param {LooseExpr | null | undefined} node
+ * @returns {boolean}
+ */
+const isSinkCall = (node) => {
+  if (!node) return false;
+  if (node.type === "AwaitExpression") return isSinkCall(node.argument);
+  if (node.type === "TSAsExpression" || node.type === "TSNonNullExpression") {
+    return isSinkCall(node.expression);
+  }
+  if (node.type !== "CallExpression" || !node.callee) return false;
+  const callee = node.callee;
+  if (callee.type === "MemberExpression" && callee.property?.name) {
+    if (CARRIER_SINK_METHODS.has(callee.property.name)) return true;
+    return CARRIER_SINKS.has(`${callee.object?.name}.${callee.property.name}`);
+  }
+  return callee.type === "Identifier" && CARRIER_SINKS.has(callee.name ?? "");
+};
+
+/**
+ * @param {LooseExpr | null | undefined} typeNode
+ * @returns {boolean}
+ */
+const isCarrierType = (typeNode) =>
+  typeNode?.type === "TSTypeReference" &&
+  typeNode.typeName?.type === "Identifier" &&
+  CARRIER_TYPES.has(typeNode.typeName.name ?? "");
+
+/**
+ * `Promise<Result<…>>` / `Promise<Maybe<…>>` or a bare carrier: what an `async` function annotated
+ * with a carrier return type looks like.
+ *
+ * @param {LooseExpr | null | undefined} typeNode
+ * @returns {boolean}
+ */
+const isCarrierReturn = (typeNode) => {
+  if (isCarrierType(typeNode)) return true;
+  if (typeNode?.type !== "TSTypeReference" || typeNode.typeName?.name !== "Promise") return false;
+  const args = /** @type {{ params?: LooseExpr[] }} */ (
+    /** @type {{ typeArguments?: unknown; typeParameters?: unknown }} */ (typeNode).typeArguments ??
+      /** @type {{ typeParameters?: unknown }} */ (typeNode).typeParameters
+  );
+  return isCarrierType(args?.params?.[0]);
+};
+
+/**
+ * The sink call, or an identifier that resolves to a `const` initialised from one:
+ * `const x = JSON.parse(s); return x;`.
+ *
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {LooseExpr | null | undefined} node
+ * @returns {boolean}
+ */
+const isSinkValue = (context, node) => {
+  if (isSinkCall(node)) return true;
+  if (node?.type !== "Identifier") return false;
+  for (
+    let scope = context.sourceCode.getScope(/** @type {never} */ (node));
+    scope;
+    scope = /** @type {typeof scope} */ (scope.upper)
+  ) {
+    const variable = scope.set.get(node.name ?? "");
+    if (!variable) continue;
+    const def = variable.defs[0];
+    const declarator =
+      /** @type {{ id?: LooseExpr; init?: LooseExpr | null; parent?: { kind?: string } } | undefined} */ (
+        def?.node
+      );
+    return (
+      def?.type === "Variable" &&
+      declarator?.parent?.kind === "const" &&
+      declarator.id?.type === "Identifier" &&
+      isSinkCall(declarator.init)
+    );
+  }
+  return false;
+};
+
+/** `res.json<Result<…>>()`: the carrier is named through the call's type argument. */
+const hasCarrierTypeArgument = (/** @type {LooseExpr} */ node) => {
+  const call =
+    /** @type {{ typeArguments?: { params?: LooseExpr[] }; typeParameters?: { params?: LooseExpr[] } }} */ (
+      /** @type {unknown} */ (node)
+    );
+  return isCarrierType((call.typeArguments ?? call.typeParameters)?.params?.[0]);
+};
+
+// an `as Result<…>` / `as Maybe<…>` expression is already reported by the TSAsExpression
+// visitor; any other cast (`as any`) must not hide the carrier type around it
+const isCarrierCast = (/** @type {LooseExpr | null | undefined} */ e) =>
+  e?.type === "TSAsExpression" && isCarrierType(e.typeAnnotation);
+
+/**
+ * Builds the check for a value flowing into a function's carrier-typed return.
+ *
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {(node: import('eslint').Rule.Node) => void} report
+ */
+const returnCheck =
+  (context, report) =>
+  /**
+   * @param {import('eslint').Rule.Node} fn
+   * @param {import('eslint').Rule.Node} at
+   * @param {LooseExpr | null | undefined} value
+   */
+  (fn, at, value) => {
+    const returnType = /** @type {{ returnType?: { typeAnnotation?: LooseExpr } }} */ (
+      /** @type {unknown} */ (fn)
+    ).returnType?.typeAnnotation;
+    if (isCarrierReturn(returnType) && !isCarrierCast(value) && isSinkValue(context, value)) {
+      report(at);
+    }
+  };
+
+/** @type {import('eslint').Rule.RuleModule} */
+const carrierSinksNeedFrom = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow plain data from JSON.parse/structuredClone/.json() being typed as Result/Maybe without Result.from/Maybe.from.",
+    },
+    schema: [],
+    messages: {
+      needsFrom:
+        "Data from JSON.parse/structuredClone/.json() is typed as Result/Maybe but carries no methods — lift it with Result.from / Maybe.from.",
+    },
+  },
+  create(context) {
+    /** @param {import('eslint').Rule.Node} node */
+    const report = (node) => context.report({ node, messageId: "needsFrom" });
+    const checkReturn = returnCheck(context, report);
+
+    return {
+      TSAsExpression(/** @type {import('eslint').Rule.Node} */ node) {
+        const expr = /** @type {LooseExpr} */ (/** @type {unknown} */ (node));
+        if (isCarrierType(expr.typeAnnotation) && isSinkValue(context, expr.expression)) {
+          report(node);
+        }
+      },
+      VariableDeclarator(/** @type {import('eslint').Rule.Node} */ node) {
+        const decl =
+          /** @type {{ id: { typeAnnotation?: { typeAnnotation: LooseExpr } }; init?: LooseExpr | null }} */ (
+            /** @type {unknown} */ (node)
+          );
+        if (isCarrierCast(decl.init)) return;
+        if (
+          isCarrierType(decl.id.typeAnnotation?.typeAnnotation) &&
+          isSinkValue(context, decl.init)
+        ) {
+          report(node);
+        }
+      },
+      AssignmentPattern(/** @type {import('eslint').Rule.Node} */ node) {
+        const pattern =
+          /** @type {{ left: { typeAnnotation?: { typeAnnotation: LooseExpr } }; right: LooseExpr }} */ (
+            /** @type {unknown} */ (node)
+          );
+        if (isCarrierCast(pattern.right)) return;
+        if (
+          isCarrierType(pattern.left.typeAnnotation?.typeAnnotation) &&
+          isSinkValue(context, pattern.right)
+        ) {
+          report(node);
+        }
+      },
+      ReturnStatement(/** @type {import('eslint').Rule.Node} */ node) {
+        const stmt = /** @type {{ argument?: LooseExpr | null }} */ (/** @type {unknown} */ (node));
+        const fn = context.sourceCode
+          .getAncestors(node)
+          .filter((a) => /Function/.test(a.type))
+          .pop();
+        // getAncestors is typed with estree nodes; every ancestor of a visited node is a rule node
+        if (fn) checkReturn(/** @type {import('eslint').Rule.Node} */ (fn), node, stmt.argument);
+      },
+      ArrowFunctionExpression(/** @type {import('eslint').Rule.Node} */ node) {
+        const arrow = /** @type {{ body: LooseExpr }} */ (/** @type {unknown} */ (node));
+        if (arrow.body.type !== "BlockStatement") checkReturn(node, node, arrow.body);
+      },
+      CallExpression(/** @type {import('eslint').Rule.Node} */ node) {
+        const call = /** @type {LooseExpr} */ (/** @type {unknown} */ (node));
+        if (isSinkCall(call) && hasCarrierTypeArgument(call)) report(node);
+      },
+    };
+  },
+};
+
 /** @type {import('eslint').ESLint.Plugin} */
 const plugin = {
   meta: {
@@ -359,6 +573,7 @@ const plugin = {
     "no-unsafe-unwrap": noUnsafeUnwrap,
     "no-deprecated-synonyms": noDeprecatedSynonyms,
     "fluent-stays-local": fluentStaysLocal,
+    "carrier-sinks-need-from": carrierSinksNeedFrom,
   },
 };
 
@@ -374,6 +589,7 @@ export const configs = {
       "@onrails/result/no-unsafe-unwrap": "warn",
       "@onrails/result/no-deprecated-synonyms": "warn",
       "@onrails/result/fluent-stays-local": "warn",
+      "@onrails/result/carrier-sinks-need-from": "warn",
     },
   },
 };