@onrails/codemod 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onrails/codemod",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Codemods for migrating onto @onrails/result (neverthrow → compat shim, and beyond)",
   "license": "MIT",
   "author": "Alan R. Soares",
@@ -42,9 +42,9 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@onrails/maybe": "0.1.4",
-    "@onrails/pattern": "0.1.4",
-    "@onrails/result": "0.1.4",
+    "@onrails/maybe": "0.2.0",
+    "@onrails/pattern": "0.2.0",
+    "@onrails/result": "0.2.0",
     "typescript": "^6.0.3"
   },
   "scripts": {

package/src/boundary-spec.ts

@@ -0,0 +1,153 @@
+/**
+ * boundary-spec.ts — the single owning module for the boundary idioms
+ * onrails enforces on consumers:
+ *
+ * 1. no `Promise<Result<…>>` in public signatures (`no-promise-result`)
+ * 2. no unsafe unwraps outside tests (`no-unsafe-unwrap`)
+ * 3. no deprecated neverthrow-era synonyms (`no-deprecated-synonyms`)
+ *
+ * The ESLint plugin (plain JS, `packages/eslint-plugin/src/index.js`) and the
+ * Biome plugin (GritQL, `packages/biome-plugin/rules/*.grit`) cannot import
+ * this module — cross-package imports are forbidden — so they hand-copy the
+ * names. `packages/codemod/test/boundary-conformance.spec.ts` reads those
+ * artifacts off disk and asserts they stay in sync with this spec.
+ *
+ * Deliberate per-engine divergences are declared in `ENGINE_DIVERGENCES`;
+ * anything not declared there is drift.
+ */
+
+// ---------------------------------------------------------------------------
+// Unsafe unwraps
+// ---------------------------------------------------------------------------
+
+/**
+ * neverthrow-compat unsafe-unwrap methods → native named equivalents.
+ * The codemod rewrites `r._unsafeUnwrap()` to `unwrapOk(r)`; the natives are
+ * still unsafe (throw on the wrong branch) and stay lint-flagged.
+ */
+export const UNSAFE_UNWRAP_MEMBER_RENAMES: ReadonlyMap<string, string> = new Map([
+  ["_unsafeUnwrap", "unwrapOk"],
+  ["_unsafeUnwrapErr", "unwrapErr"],
+]);
+
+/** Free-function unwraps that throw on the unhappy branch. */
+export const UNSAFE_UNWRAP_CALL_NAMES = ["unwrapOk", "unwrapErr", "unwrap"] as const;
+
+/** Every identifier the `no-unsafe-unwrap` rule flags, across engines. */
+export const UNSAFE_UNWRAP_NAMES: ReadonlySet<string> = new Set([
+  ...UNSAFE_UNWRAP_MEMBER_RENAMES.keys(),
+  ...UNSAFE_UNWRAP_CALL_NAMES,
+]);
+
+/**
+ * Matches compat unsafe-unwrap member calls (`._unsafeUnwrap(` /
+ * `._unsafeUnwrapErr(`) in raw source. Derived from the rename map so the
+ * codemod's compat-only detection cannot drift from the spec.
+ */
+export const UNSAFE_UNWRAP_MEMBER_CALL_RE = new RegExp(
+  String.raw`\.(?:${[...UNSAFE_UNWRAP_MEMBER_RENAMES.keys()].join("|")})\s*\(`,
+);
+
+// ---------------------------------------------------------------------------
+// Deprecated synonyms
+// ---------------------------------------------------------------------------
+
+export interface DeprecatedSynonym {
+  /** The deprecated identifier as it appears in consumer code. */
+  readonly name: string;
+  /** `method` — flagged as `x.name(…)`; `call` — flagged as `name(…)`. */
+  readonly form: "method" | "call";
+  /** Canonical replacement identifier. */
+  readonly canonical: string;
+  /** Extra guidance when the rename is not a plain identifier swap. */
+  readonly hint?: string;
+}
+
+/**
+ * Deprecated neverthrow/fp-era synonyms → canonical onrails names.
+ * Matching is name-based in every engine — neither GritQL nor the ESLint
+ * rules scope by import, so same-named calls from other libraries (RxJS
+ * `of`, fp-ts `fold`) are flagged too.
+ */
+export const DEPRECATED_SYNONYMS: readonly DeprecatedSynonym[] = [
+  { name: "chain", form: "method", canonical: "flatMap" },
+  {
+    name: "isOk",
+    form: "method",
+    canonical: "isOk",
+    hint: "await the ResultAsync, then narrow with the isOk() free function",
+  },
+  {
+    name: "isErr",
+    form: "method",
+    canonical: "isErr",
+    hint: "await the ResultAsync, then narrow with the isErr() free function",
+  },
+  { name: "fold", form: "call", canonical: "match" },
+  { name: "matchResult", form: "call", canonical: "match" },
+  { name: "matchMaybe", form: "call", canonical: "match" },
+  { name: "getOrElse", form: "call", canonical: "unwrapOr" },
+  { name: "sequenceTupleAsync", form: "call", canonical: "ResultAsync.combineTuple" },
+  { name: "collect", form: "call", canonical: "combine" },
+  { name: "of", form: "call", canonical: "ok", hint: "or some() for Maybe" },
+];
+
+/** Flat old-name → canonical-name view of {@link DEPRECATED_SYNONYMS}. */
+export const DEPRECATED_SYNONYM_RENAMES: ReadonlyMap<string, string> = new Map(
+  DEPRECATED_SYNONYMS.map((s) => [s.name, s.canonical]),
+);
+
+// ---------------------------------------------------------------------------
+// Rule descriptors
+// ---------------------------------------------------------------------------
+
+/** `Promise<Result<…>>` in a type position → `ResultAsync<T, E>`. */
+export const NO_PROMISE_RESULT_RULE = {
+  id: "no-promise-result",
+  replacement: "ResultAsync",
+  boundaryHelpers: ["fromAsync", "tryAsync"],
+  message:
+    "Promise<Result<…>> in a type position — use ResultAsync<T, E> at the boundary (fromAsync / tryAsync).",
+} as const;
+
+/** Unsafe unwraps outside tests. Message is shared verbatim by both engines. */
+export const NO_UNSAFE_UNWRAP_RULE = {
+  id: "no-unsafe-unwrap",
+  message:
+    "Avoid _unsafeUnwrap* and unwrap* outside tests — use match(), resolve(), or yieldResult() in tryGen.",
+} as const;
+
+/** Deprecated synonym identifiers. Per-engine message wording differs. */
+export const NO_DEPRECATED_SYNONYMS_RULE = {
+  id: "no-deprecated-synonyms",
+} as const;
+
+// ---------------------------------------------------------------------------
+// Declared divergences
+// ---------------------------------------------------------------------------
+
+export interface EngineDivergence {
+  readonly rule: string;
+  /** Engine whose behaviour differs from the other(s). */
+  readonly engine: "eslint" | "biome" | "codemod";
+  /** Stable id the conformance test keys on. */
+  readonly divergence: string;
+  readonly detail: string;
+}
+
+/**
+ * Deliberate cross-engine behaviour differences. The conformance test treats
+ * these as declared (allowed); any other difference is accidental drift.
+ */
+export const ENGINE_DIVERGENCES: readonly EngineDivergence[] = [
+  {
+    rule: "no-unsafe-unwrap",
+    engine: "biome",
+    divergence: "no-test-file-exemption",
+    detail:
+      "The ESLint rule skips *.spec.* / *.test.* files where unsafe unwraps are " +
+      "acceptable; GritQL patterns cannot read the file path, so the Biome rule " +
+      "flags test code too. Suppress with a biome-ignore comment or a linter " +
+      "override for test globs.",
+  },
+];

package/src/constants.ts

@@ -1,3 +1,5 @@
+import { UNSAFE_UNWRAP_MEMBER_CALL_RE, UNSAFE_UNWRAP_MEMBER_RENAMES } from "./boundary-spec.js";
+
 export const SKIP = new Set([
   "node_modules",
   "dist",
@@ -16,7 +18,7 @@ export const DEP_KEYS = ["dependencies", "devDependencies", "peerDependencies"]
 export const TYPE_ONLY_NATIVE = new Set(["Result", "Ok", "Err", "UnexpectedError"]);
 export const COMPAT_ONLY_PATTERNS = [
   { pattern: /\bResult\.(combine|fromThrowable)\b/, label: "Result static helper" },
-  { pattern: /\._unsafeUnwrap(Err)?\s*\(/, label: "unsafe compat unwrap" },
+  { pattern: UNSAFE_UNWRAP_MEMBER_CALL_RE, label: "unsafe compat unwrap" },
 ] as const;
 export const RESULT_SPECIFIC_CHAIN_METHODS = new Set([
   "andThen",
@@ -57,8 +59,5 @@ export const TEE_METHODS = new Map([
   ["orTee", "tapErr"],
 ]);
 export const PREDICATE_METHODS = new Set(["isOk", "isErr"]);
-export const UNSAFE_UNWRAP_METHODS = new Map([
-  ["_unsafeUnwrap", "unwrapOk"],
-  ["_unsafeUnwrapErr", "unwrapErr"],
-]);
+export const UNSAFE_UNWRAP_METHODS = new Map(UNSAFE_UNWRAP_MEMBER_RENAMES);
 export const SAFE_BASE_PATTERNS = [/^(ok|err)\s*\(/, /^Result\./, /^[a-zA-Z_$][\w$]*$/] as const;

package/src/index.ts

@@ -1,6 +1,20 @@
 #!/usr/bin/env bun
 import { main } from "./cli.js";
 
+export {
+  DEPRECATED_SYNONYM_RENAMES,
+  DEPRECATED_SYNONYMS,
+  type DeprecatedSynonym,
+  ENGINE_DIVERGENCES,
+  type EngineDivergence,
+  NO_DEPRECATED_SYNONYMS_RULE,
+  NO_PROMISE_RESULT_RULE,
+  NO_UNSAFE_UNWRAP_RULE,
+  UNSAFE_UNWRAP_CALL_NAMES,
+  UNSAFE_UNWRAP_MEMBER_CALL_RE,
+  UNSAFE_UNWRAP_MEMBER_RENAMES,
+  UNSAFE_UNWRAP_NAMES,
+} from "./boundary-spec.js";
 export { rewriteCompatMethodChainsToNative } from "./chains.js";
 export { main } from "./cli.js";
 export { computeFileChange } from "./file-change.js";

package/src/tersify-utils.ts

@@ -0,0 +1,177 @@
+import ts from "typescript";
+
+// Helper to check for single statement return
+export function getSingleReturnExpression(statement: ts.Statement): ts.Expression | undefined {
+  if (ts.isReturnStatement(statement)) {
+    return statement.expression;
+  }
+  if (ts.isBlock(statement)) {
+    if (statement.statements.length === 1) {
+      const single = statement.statements[0];
+      if (single && ts.isReturnStatement(single)) {
+        return single.expression;
+      }
+    }
+  }
+  return undefined;
+}
+
+// Helper to check if body uses 'this' or 'arguments'
+export function usesThisOrArguments(body: ts.Node): boolean {
+  let found = false;
+  const visit = (n: ts.Node) => {
+    if (found) return;
+    if (n.kind === ts.SyntaxKind.ThisKeyword) {
+      found = true;
+      return;
+    }
+    if (ts.isIdentifier(n) && n.text === "arguments") {
+      found = true;
+      return;
+    }
+    if (
+      ts.isFunctionDeclaration(n) ||
+      ts.isFunctionExpression(n) ||
+      ts.isArrowFunction(n) ||
+      ts.isMethodDeclaration(n) ||
+      ts.isGetAccessorDeclaration(n) ||
+      ts.isSetAccessorDeclaration(n)
+    ) {
+      return; // Stop recursion for nested scopes
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(body, visit);
+  return found;
+}
+
+// Helper to check if identifier referenced before pos
+export function isIdentifierReferencedBefore(
+  name: string,
+  pos: number,
+  sf: ts.SourceFile,
+): boolean {
+  let referenced = false;
+  const visit = (n: ts.Node) => {
+    if (referenced) return;
+    if (n.getStart(sf) >= pos) return;
+    if (ts.isIdentifier(n) && n.text === name) {
+      const parent = n.parent;
+      if (parent) {
+        if (ts.isPropertyAccessExpression(parent) && parent.name === n) {
+          return;
+        }
+        if (ts.isPropertyAssignment(parent) && parent.name === n) {
+          return;
+        }
+        if (ts.isMethodDeclaration(parent) && parent.name === n) {
+          return;
+        }
+        if (ts.isPropertyDeclaration(parent) && parent.name === n) {
+          return;
+        }
+        if (ts.isBindingElement(parent) && parent.propertyName === n) {
+          return;
+        }
+      }
+      referenced = true;
+      return;
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(sf, visit);
+  return referenced;
+}
+
+export function getTypeParametersText(
+  node: ts.FunctionDeclaration | ts.FunctionExpression,
+  sf: ts.SourceFile,
+): string {
+  if (node.typeParameters && node.typeParameters.length > 0) {
+    const params = node.typeParameters.map((p) => p.getText(sf));
+    return params.length === 1 ? `<${params[0]},>` : `<${params.join(", ")}>`;
+  }
+  return "";
+}
+
+export const isSimpleExpression = (expr: ts.Expression): boolean =>
+  ts.isIdentifier(expr) ||
+  ts.isPropertyAccessExpression(expr) ||
+  ts.isElementAccessExpression(expr) ||
+  ts.isCallExpression(expr);
+
+export function containsConditional(node: ts.Node): boolean {
+  if (ts.isConditionalExpression(node)) {
+    return true;
+  }
+  let found = false;
+  ts.forEachChild(node, (child) => {
+    if (found) return;
+    if (containsConditional(child)) {
+      found = true;
+    }
+  });
+  return found;
+}
+
+// A concise arrow body that is — or unwraps through `as` / `satisfies` to — an
+// object literal must be parenthesized, else `{ … }` parses as a block body.
+export function startsWithObjectLiteral(expr: ts.Expression): boolean {
+  let e: ts.Expression = expr;
+  while (ts.isAsExpression(e) || ts.isSatisfiesExpression(e)) {
+    e = e.expression;
+  }
+  return ts.isObjectLiteralExpression(e);
+}
+
+export function getTernaryBranchText(node: ts.Expression, sf: ts.SourceFile): string {
+  let current = node;
+  let hasParens = false;
+  while (ts.isParenthesizedExpression(current)) {
+    current = current.expression;
+    hasParens = true;
+  }
+
+  let unwrapped: ts.Expression | undefined;
+  if (ts.isJsxFragment(current)) {
+    const children = current.children;
+    const nonTriviaChildren = children.filter((child) => {
+      if (ts.isJsxText(child)) {
+        return !child.containsOnlyTriviaWhiteSpaces;
+      }
+      return true;
+    });
+    if (nonTriviaChildren.length === 1) {
+      const soleChild = nonTriviaChildren[0];
+      if (soleChild && ts.isJsxExpression(soleChild) && soleChild.expression) {
+        unwrapped = soleChild.expression;
+      }
+    }
+  } else if (ts.isJsxElement(current)) {
+    const tagName = current.openingElement.tagName.getText(sf);
+    if (tagName === "Fragment" || tagName === "React.Fragment" || tagName.endsWith(".Fragment")) {
+      if (current.openingElement.attributes.properties.length === 0) {
+        const children = current.children;
+        const nonTriviaChildren = children.filter((child) => {
+          if (ts.isJsxText(child)) {
+            return !child.containsOnlyTriviaWhiteSpaces;
+          }
+          return true;
+        });
+        if (nonTriviaChildren.length === 1) {
+          const soleChild = nonTriviaChildren[0];
+          if (soleChild && ts.isJsxExpression(soleChild) && soleChild.expression) {
+            unwrapped = soleChild.expression;
+          }
+        }
+      }
+    }
+  }
+
+  if (unwrapped) {
+    const unwrappedText = getTernaryBranchText(unwrapped, sf);
+    return hasParens ? `(${unwrappedText})` : unwrappedText;
+  }
+
+  return node.getText(sf);
+}

package/src/tersify.ts

@@ -3,118 +3,18 @@ import ts from "typescript";
 import { edit, spanEdit, walkSource } from "./ast.js";
 import { applyEditStep, byStartDesc } from "./chains.js";
 import { scanIfToSwitchSequences } from "./switch.js";
+import {
+  containsConditional,
+  getSingleReturnExpression,
+  getTernaryBranchText,
+  getTypeParametersText,
+  isIdentifierReferencedBefore,
+  isSimpleExpression,
+  startsWithObjectLiteral,
+  usesThisOrArguments,
+} from "./tersify-utils.js";
 import type { Edit } from "./types.js";
 
-// Helper to check for single statement return
-function getSingleReturnExpression(statement: ts.Statement): ts.Expression | undefined {
-  if (ts.isReturnStatement(statement)) {
-    return statement.expression;
-  }
-  if (ts.isBlock(statement)) {
-    if (statement.statements.length === 1) {
-      const single = statement.statements[0];
-      if (single && ts.isReturnStatement(single)) {
-        return single.expression;
-      }
-    }
-  }
-  return undefined;
-}
-
-// Helper to check if body uses 'this' or 'arguments'
-function usesThisOrArguments(body: ts.Node): boolean {
-  let found = false;
-  const visit = (n: ts.Node) => {
-    if (found) return;
-    if (n.kind === ts.SyntaxKind.ThisKeyword) {
-      found = true;
-      return;
-    }
-    if (ts.isIdentifier(n) && n.text === "arguments") {
-      found = true;
-      return;
-    }
-    if (
-      ts.isFunctionDeclaration(n) ||
-      ts.isFunctionExpression(n) ||
-      ts.isArrowFunction(n) ||
-      ts.isMethodDeclaration(n) ||
-      ts.isGetAccessorDeclaration(n) ||
-      ts.isSetAccessorDeclaration(n)
-    ) {
-      return; // Stop recursion for nested scopes
-    }
-    ts.forEachChild(n, visit);
-  };
-  ts.forEachChild(body, visit);
-  return found;
-}
-
-// Helper to check if identifier referenced before pos
-function isIdentifierReferencedBefore(name: string, pos: number, sf: ts.SourceFile): boolean {
-  let referenced = false;
-  const visit = (n: ts.Node) => {
-    if (referenced) return;
-    if (n.getStart(sf) >= pos) return;
-    if (ts.isIdentifier(n) && n.text === name) {
-      const parent = n.parent;
-      if (parent) {
-        if (ts.isPropertyAccessExpression(parent) && parent.name === n) {
-          return;
-        }
-        if (ts.isPropertyAssignment(parent) && parent.name === n) {
-          return;
-        }
-        if (ts.isMethodDeclaration(parent) && parent.name === n) {
-          return;
-        }
-        if (ts.isPropertyDeclaration(parent) && parent.name === n) {
-          return;
-        }
-        if (ts.isBindingElement(parent) && parent.propertyName === n) {
-          return;
-        }
-      }
-      referenced = true;
-      return;
-    }
-    ts.forEachChild(n, visit);
-  };
-  ts.forEachChild(sf, visit);
-  return referenced;
-}
-
-function getTypeParametersText(
-  node: ts.FunctionDeclaration | ts.FunctionExpression,
-  sf: ts.SourceFile,
-): string {
-  if (node.typeParameters && node.typeParameters.length > 0) {
-    const params = node.typeParameters.map((p) => p.getText(sf));
-    return params.length === 1 ? `<${params[0]},>` : `<${params.join(", ")}>`;
-  }
-  return "";
-}
-
-const isSimpleExpression = (expr: ts.Expression): boolean =>
-  ts.isIdentifier(expr) ||
-  ts.isPropertyAccessExpression(expr) ||
-  ts.isElementAccessExpression(expr) ||
-  ts.isCallExpression(expr);
-
-function containsConditional(node: ts.Node): boolean {
-  if (ts.isConditionalExpression(node)) {
-    return true;
-  }
-  let found = false;
-  ts.forEachChild(node, (child) => {
-    if (found) return;
-    if (containsConditional(child)) {
-      found = true;
-    }
-  });
-  return found;
-}
-
 function tryTersifyIfElse(node: ts.Node, sf: ts.SourceFile): Maybe<Edit> {
   if (ts.isIfStatement(node) && node.elseStatement) {
     const x = getSingleReturnExpression(node.thenStatement);
@@ -138,24 +38,14 @@ function tryTersifyIfElse(node: ts.Node, sf: ts.SourceFile): Maybe<Edit> {
         return some(spanEdit(node, sf, edit(text)));
       }
 
-      const xText = x.getText(sf);
-      const yText = y.getText(sf);
+      const xText = getTernaryBranchText(x, sf);
+      const yText = getTernaryBranchText(y, sf);
       return some(spanEdit(node, sf, edit(`return ${condText} ? ${xText} : ${yText};`)));
     }
   }
   return none();
 }
 
-// A concise arrow body that is — or unwraps through `as` / `satisfies` to — an
-// object literal must be parenthesized, else `{ … }` parses as a block body.
-function startsWithObjectLiteral(expr: ts.Expression): boolean {
-  let e: ts.Expression = expr;
-  while (ts.isAsExpression(e) || ts.isSatisfiesExpression(e)) {
-    e = e.expression;
-  }
-  return ts.isObjectLiteralExpression(e);
-}
-
 function tryTersifyArrowBlock(node: ts.Node, sf: ts.SourceFile): Maybe<Edit> {
   if (ts.isArrowFunction(node) && ts.isBlock(node.body)) {
     const expr = getSingleReturnExpression(node.body);
@@ -353,8 +243,8 @@ function tryTersifyTernaryOrBooleanSequence(
       const needsParens = !isSimpleExpression(stmt.expression);
       text = needsParens ? `return !(${condText});` : `return !${condText};`;
     } else {
-      const xText = x.getText(sf);
-      const yText = y.getText(sf);
+      const xText = getTernaryBranchText(x, sf);
+      const yText = getTernaryBranchText(y, sf);
       text = `return ${condText} ? ${xText} : ${yText};`;
     }