@onrails/eslint-plugin 0.1.3 → 0.2.0

package/README.md

@@ -21,6 +21,7 @@ export default [
       "@onrails/no-promise-result": "warn",
       "@onrails/no-unsafe-unwrap": "warn",
       "@onrails/no-deprecated-synonyms": "warn",
+      "@onrails/fluent-stays-local": "warn",
     },
   },
 ];
@@ -48,6 +49,8 @@ export default [
 | `@onrails/no-promise-result` | Flags `Promise<Result<…>>` in source — public APIs should return `ResultAsync` |
 | `@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.3",
+  "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

@@ -200,6 +200,368 @@ const noDeprecatedSynonyms = {
   },
 };
 
+/**
+ * Fluent wrapper types and serialize-sink names. Hand-copied from
+ * `@onrails/codemod` `src/boundary-spec.ts` (cross-package imports are
+ * forbidden); `packages/codemod/test/boundary-conformance.spec.ts` keeps the
+ * copies in sync.
+ */
+const FLUENT_WRAPPER_TYPES = new Set(["FluentResult", "FluentMaybe"]);
+const FLUENT_ESCAPE_SINKS = new Set(["postMessage", "structuredClone", "JSON.stringify"]);
+/** Fluent methods that exit the wrapper — a chain ending here is already plain data. */
+const FLUENT_TERMINAL_METHODS = new Set(["toResult", "toMaybe", "toString", "match", "unwrapOr"]);
+
+/**
+ * Loose parent-chain node shape for structural classification — mirrors
+ * {@link TsTypeReference} for nodes outside estree's bundled types
+ * (`TSTypeAnnotation`, `PropertyDefinition`, `VariableDeclarator`, …).
+ *
+ * @typedef {object} LooseNode
+ * @property {string} type
+ * @property {string} [name]
+ * @property {LooseNode} [parent]
+ * @property {LooseNode} [returnType]
+ * @property {LooseNode} [object]
+ * @property {LooseNode} [property]
+ * @property {LooseNode} [callee]
+ */
+
+/**
+ * @param {unknown} node
+ * @returns {LooseNode}
+ */
+const asLoose = (node) => /** @type {LooseNode} */ (node);
+
+/**
+ * @param {LooseNode} node
+ * @returns {string}
+ */
+const calleeName = (node) => {
+  if (node.type === "Identifier") return node.name ?? "";
+  if (
+    node.type === "MemberExpression" &&
+    node.object?.type === "Identifier" &&
+    node.property?.type === "Identifier"
+  )
+    return `${node.object.name}.${node.property.name}`;
+  return "";
+};
+
+/**
+ * True when `node` still holds a fluent wrapper — a call chain rooted at
+ * `fluent(...)` that hasn't reached a terminal (`toResult`, `match`, …) yet.
+ * `fluent(r).toResult()` is plain data by the time it reaches a sink;
+ * `fluent(r)` and `fluent(r).map(f)` are not. Purely syntactic: a
+ * `fluent(...)` result stashed in a variable first is out of reach without
+ * type information.
+ *
+ * @param {unknown} node
+ * @returns {boolean}
+ */
+const isFluentChain = (node) => {
+  if (!node) return false;
+  const loose = asLoose(node);
+  if (loose.type !== "CallExpression" || !loose.callee) return false;
+  if (loose.callee.type === "Identifier") return loose.callee.name === "fluent";
+  if (loose.callee.type === "MemberExpression") {
+    const method = loose.callee.property?.name;
+    if (method && FLUENT_TERMINAL_METHODS.has(method)) return false;
+    return isFluentChain(loose.callee.object);
+  }
+  return false;
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const fluentStaysLocal = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow FluentResult/FluentMaybe escaping its function — as a return type, an exported binding, a stored field, or an argument to a serialize/postMessage/cache call.",
+    },
+    schema: [],
+    messages: {
+      returnType:
+        "{{name}} as a function return type lets the fluent wrapper escape — call toResult()/toMaybe()/toString() and return plain data instead.",
+      exported:
+        "{{name}} on an exported binding lets the fluent wrapper escape its module — call toResult()/toMaybe()/toString() before exporting.",
+      storedField:
+        "{{name}} on a stored field lets the fluent wrapper escape — call toResult()/toMaybe()/toString() before storing it.",
+      serializeArg:
+        "Passing a fluent(...) chain into {{sink}}() serializes/transfers a closure — call toResult()/toMaybe()/toString() first.",
+    },
+  },
+  create(context) {
+    return {
+      TSTypeReference(/** @type {import('eslint').Rule.Node} */ node) {
+        const typeRef = asTsTypeReference(node);
+        const typeName = typeRef.typeName;
+        if (typeName.type !== "Identifier" || !FLUENT_WRAPPER_TYPES.has(typeName.name ?? ""))
+          return;
+        const name = typeName.name;
+
+        const annotation = asLoose(node).parent;
+        if (annotation?.type !== "TSTypeAnnotation") return;
+        const owner = annotation.parent;
+        if (!owner) return;
+
+        if (
+          [
+            "FunctionDeclaration",
+            "FunctionExpression",
+            "ArrowFunctionExpression",
+            "TSMethodSignature",
+            "TSDeclareFunction",
+            "TSFunctionType",
+            "TSCallSignatureDeclaration",
+          ].includes(owner.type) &&
+          owner.returnType === annotation
+        ) {
+          context.report({ node, messageId: "returnType", data: { name } });
+          return;
+        }
+
+        // A variable's type annotation hangs off its `id` pattern, e.g.
+        // `const chain: FluentResult<…>` attaches to the Identifier "chain",
+        // whose parent is the VariableDeclarator.
+        if (owner.type === "Identifier" && owner.parent?.type === "VariableDeclarator") {
+          if (owner.parent.parent?.parent?.type === "ExportNamedDeclaration") {
+            context.report({ node, messageId: "exported", data: { name } });
+            return;
+          }
+        }
+
+        if (owner.type === "PropertyDefinition" || owner.type === "TSPropertySignature") {
+          context.report({ node, messageId: "storedField", data: { name } });
+        }
+      },
+      CallExpression(node) {
+        const sink = calleeName(asLoose(node.callee));
+        if (!FLUENT_ESCAPE_SINKS.has(sink)) return;
+        for (const arg of node.arguments) {
+          if (isFluentChain(arg)) {
+            context.report({ node: arg, messageId: "serializeArg", data: { sink } });
+          }
+        }
+      },
+    };
+  },
+};
+
+/**
+ * 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: {
@@ -210,6 +572,8 @@ const plugin = {
     "no-promise-result": noPromiseResult,
     "no-unsafe-unwrap": noUnsafeUnwrap,
     "no-deprecated-synonyms": noDeprecatedSynonyms,
+    "fluent-stays-local": fluentStaysLocal,
+    "carrier-sinks-need-from": carrierSinksNeedFrom,
   },
 };
 
@@ -224,6 +588,8 @@ export const configs = {
       "@onrails/result/no-promise-result": "warn",
       "@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",
     },
   },
 };