@onrails/codemod 0.2.8 → 0.3.0

package/README.md

@@ -46,6 +46,9 @@ bunx @onrails/codemod /path/to/target-repo \
 # stage 2: compat shim -> native imports
 bunx @onrails/codemod /path/to/target-repo --to-native --dry
 bunx @onrails/codemod /path/to/target-repo --to-native
+
+# optional: build carriers with constructors instead of object literals
+bunx @onrails/codemod /path/to/target-repo --literals --dry
 ```
 
 After applying:
@@ -58,6 +61,24 @@ bun typecheck
 bun test
 ```
 
+## Literal rewrite
+
+`--literals` rewrites hand-built carrier literals to constructor calls, so the
+code keeps working if carriers ever stop being plain objects:
+
+| Before | After |
+|---|---|
+| `{ _tag: "Ok", value: x }` | `ok(x)` |
+| `{ _tag: "Err", error: e }` | `err(e)` |
+| `{ _tag: "Some", value: x }` | `some(x)` (`@onrails/maybe`) |
+| `{ _tag: "None" }` | `none()` (`@onrails/maybe`) |
+
+Only exact shapes are touched. Literals with extra keys, spreads, computed keys
+or a non-literal `_tag` are left alone, as are files that already bind `ok`,
+`err`, `some` or `none` to something else. A trailing `as const` is dropped
+with the literal. Imports are added or merged. It works against the current
+API, so it can run before any breaking release.
+
 ## Native migration
 
 `--to-native` is intentionally conservative. It rewrites imports that have a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onrails/codemod",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "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.2.3",
-    "@onrails/pattern": "^0.3.3",
-    "@onrails/result": "^0.4.0",
+    "@onrails/maybe": "^0.2.5",
+    "@onrails/pattern": "^0.3.5",
+    "@onrails/result": "^0.4.2",
     "typescript": "^7.0.2",
     "typescript6": "npm:typescript@^6.0.3"
   },

package/src/boundary-spec.ts

@@ -147,6 +147,28 @@ export const FLUENT_STAYS_LOCAL_RULE = {
     "FluentResult/FluentMaybe must stay local — it was flagged as a return type, an exported binding, a stored field, or an argument to a serialize/postMessage/cache call. Call toResult()/toMaybe()/toString() before it leaves the function.",
 } as const;
 
+// ---------------------------------------------------------------------------
+// Carrier sinks (prototype carriers)
+// ---------------------------------------------------------------------------
+
+/** Carrier types whose methods live on a prototype that plain-data routes drop. */
+export const CARRIER_TYPES = ["Result", "Maybe"] as const;
+
+/** Deserialization sinks whose output is plain data, whatever the cast claims. */
+export const CARRIER_SINK_NAMES = ["JSON.parse", "structuredClone", ".json()"] as const;
+
+/**
+ * Plain data from a deserialization sink typed as `Result` / `Maybe` without
+ * `Result.from` / `Maybe.from`: the type claims methods the value lacks.
+ */
+export const CARRIER_SINKS_NEED_FROM_RULE = {
+  id: "carrier-sinks-need-from",
+  carriers: CARRIER_TYPES,
+  sinks: CARRIER_SINK_NAMES,
+  message:
+    "Data from JSON.parse/structuredClone/.json() is typed as Result/Maybe but carries no methods — lift it with Result.from / Maybe.from.",
+} as const;
+
 // ---------------------------------------------------------------------------
 // Declared divergences
 // ---------------------------------------------------------------------------
@@ -200,4 +222,17 @@ export const ENGINE_DIVERGENCES: readonly EngineDivergence[] = [
       "cannot express the serialize/postMessage/cache argument heuristic at " +
       "all, since that needs expression-shape traversal, not a type pattern.",
   },
+  {
+    rule: CARRIER_SINKS_NEED_FROM_RULE.id,
+    engine: "biome",
+    divergence: "cast-form-only",
+    detail:
+      "The ESLint rule flags `JSON.parse(x) as Result<T, E>` and also the " +
+      "flow forms: `const r: Result<T, E> = JSON.parse(x)`, `return JSON.parse(x)` " +
+      "from a function annotated to return a carrier (or Promise of one), a " +
+      "carrier-typed parameter default, a `const` holding a sink result that is " +
+      "later cast, annotated or returned, and `res.json<Result<T, E>>()`. GritQL " +
+      "cannot relate a declarator, return type or binding to its use, so the " +
+      "Biome rule only matches the direct `as` cast form.",
+  },
 ];

package/src/cli.ts

@@ -17,6 +17,7 @@ const applyArg = (s: ArgState, a: string): ArgState =>
     .withEither("--dry", "-n", () => ({ ...s, dry: true }))
     .with("--to-native", () => ({ ...s, mode: "native" }))
     .with("--tersify", () => ({ ...s, mode: "tersify" }))
+    .with("--literals", () => ({ ...s, mode: "literals" }))
     .with(
       (x) => x.startsWith(ONRAILS_FLAG),
       (x) => ({ ...s, onrails: resolve(x.slice(ONRAILS_FLAG.length)) }),
@@ -28,7 +29,7 @@ const applyArg = (s: ArgState, a: string): ArgState =>
     .otherwise(() => s);
 
 const USAGE =
-  "usage: onrails-codemod-neverthrow <target-dir> [--dry] [--to-native] [--tersify] [--onrails=<abs-path>]";
+  "usage: onrails-codemod-neverthrow <target-dir> [--dry] [--to-native] [--tersify] [--literals] [--onrails=<abs-path>]";
 
 export function parseArgs(argv: string[]): Result<Args, string> {
   const initial: ArgState = {

package/src/file-change.ts

@@ -3,6 +3,7 @@ import { countOccurrences } from "./ast.js";
 import { rewriteCompatMethodChainsToNative } from "./chains.js";
 import { COMPAT_SPEC, IMPORT_RE, NATIVE_SPEC } from "./constants.js";
 import { rewriteCompatImportsToNative } from "./imports.js";
+import { rewriteCarrierLiterals } from "./literals.js";
 import { tersify } from "./tersify.js";
 import type { ComputedChange, FileChange, Mode, ModeStrategy, Warning } from "./types.js";
 import {
@@ -43,6 +44,13 @@ const MODES: Record<Mode, ModeStrategy> = {
     warnings: () => [],
     countAfter: () => 0,
   },
+  literals: {
+    countBefore: (src) => countOccurrences(src, "_tag"),
+    earlyExit: (_src, before) => before === 0,
+    transform: rewriteCarrierLiterals,
+    warnings: () => [],
+    countAfter: () => 0,
+  },
 };
 
 export const computeFileChange = (src: string, mode: Mode, jsx = false): Maybe<ComputedChange> => {

package/src/index.ts

@@ -2,6 +2,9 @@
 import { main } from "./cli.js";
 
 export {
+  CARRIER_SINK_NAMES,
+  CARRIER_SINKS_NEED_FROM_RULE,
+  CARRIER_TYPES,
   DEPRECATED_SYNONYM_RENAMES,
   DEPRECATED_SYNONYMS,
   type DeprecatedSynonym,
@@ -19,6 +22,7 @@ export { rewriteCompatMethodChainsToNative } from "./chains.js";
 export { main } from "./cli.js";
 export { computeFileChange } from "./file-change.js";
 export { rewriteCompatImportsToNative } from "./imports.js";
+export { rewriteCarrierLiterals } from "./literals.js";
 export { computePkgRewrite } from "./pkg.js";
 export { tersify } from "./tersify.js";
 export { collectNativeMigrationWarnings } from "./warnings.js";

package/src/literals.ts

@@ -0,0 +1,251 @@
+import ts from "typescript6";
+import { walkSource } from "./ast.js";
+import { NATIVE_SPEC } from "./constants.js";
+
+const MAYBE_SPEC = "@onrails/maybe";
+
+type Shape = { readonly fn: string; readonly spec: string; readonly field: string | null };
+
+const SHAPES: Record<string, Shape> = {
+  Ok: { fn: "ok", spec: NATIVE_SPEC, field: "value" },
+  Err: { fn: "err", spec: NATIVE_SPEC, field: "error" },
+  Some: { fn: "some", spec: MAYBE_SPEC, field: "value" },
+  None: { fn: "none", spec: MAYBE_SPEC, field: null },
+};
+
+type Prop = { readonly key: string; readonly text: string };
+type LiteralEdit = { start: number; end: number; text: string; name: string; spec: string };
+
+const keyOf = (name: ts.PropertyName): string | null =>
+  ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : null;
+
+/** `key: value` / `key` shorthand pairs; null when a spread, method, accessor or computed key is present. */
+const readProps = (lit: ts.ObjectLiteralExpression): readonly Prop[] | null => {
+  const props: Prop[] = [];
+  for (const p of lit.properties) {
+    if (ts.isPropertyAssignment(p)) {
+      const key = keyOf(p.name);
+      if (key === null) return null;
+      props.push({ key, text: p.initializer.getText() });
+    } else if (ts.isShorthandPropertyAssignment(p)) {
+      props.push({ key: p.name.text, text: p.name.text });
+    } else return null;
+  }
+  return props;
+};
+
+const tagOf = (props: readonly Prop[]): string | undefined => {
+  const raw = props.find((p) => p.key === "_tag")?.text;
+  return raw?.match(/^(["'])(\w+)\1$/)?.[2];
+};
+
+const bindingNames = (name: ts.BindingName): readonly string[] =>
+  ts.isIdentifier(name)
+    ? [name.text]
+    : name.elements.flatMap((el) => (ts.isOmittedExpression(el) ? [] : bindingNames(el.name)));
+
+const declaredIn = (statements: readonly ts.Statement[]): readonly string[] =>
+  statements.flatMap((st) => {
+    if ((ts.isFunctionDeclaration(st) || ts.isClassDeclaration(st)) && st.name)
+      return [st.name.text];
+    if (ts.isVariableStatement(st)) {
+      return st.declarationList.declarations.flatMap((d) => bindingNames(d.name));
+    }
+    return [];
+  });
+
+/** The genuine value binding of an onrails constructor: `import { ok }` with no alias, not type-only. */
+const isPlainValueSpecifier = (el: ts.ImportSpecifier, clauseTypeOnly: boolean): boolean =>
+  !clauseTypeOnly && !el.isTypeOnly && el.propertyName === undefined;
+
+/** Locals the file's imports bind to something other than the onrails constructor of the same name. */
+const importedLocals = (sf: ts.SourceFile): readonly string[] =>
+  sf.statements.flatMap((st) => {
+    if (!ts.isImportDeclaration(st)) return [];
+    const spec = ts.isStringLiteral(st.moduleSpecifier) ? st.moduleSpecifier.text : "";
+    const onrails = spec === NATIVE_SPEC || spec === MAYBE_SPEC;
+    const clause = st.importClause;
+    const nb = clause?.namedBindings;
+    const named =
+      nb && ts.isNamedImports(nb)
+        ? nb.elements.filter(
+            (el) => !onrails || !isPlainValueSpecifier(el, clause?.isTypeOnly ?? false),
+          )
+        : [];
+    return [
+      ...(clause?.name ? [clause.name.text] : []),
+      ...(nb && ts.isNamespaceImport(nb) ? [nb.name.text] : []),
+      ...named.map((el) => el.name.text),
+    ];
+  });
+
+/** `var` names declared anywhere under `root`, stopping at nested functions (they hoist to those). */
+const hoistedVars = (root: ts.Node): readonly string[] => {
+  const out: string[] = [];
+  const visit = (n: ts.Node): void => {
+    if (ts.isFunctionLike(n) || ts.isClassLike(n)) return;
+    if (ts.isVariableDeclarationList(n) && !(n.flags & ts.NodeFlags.BlockScoped)) {
+      for (const d of n.declarations) out.push(...bindingNames(d.name));
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(root, (child) => {
+    // the function's own parameters and name are not `var`s; its body is
+    if (!ts.isFunctionLike(root) || child === (root as ts.FunctionLikeDeclaration).body)
+      visit(child);
+  });
+  return out;
+};
+
+/** Names a single scope-creating node binds for the code inside it. */
+const boundBy = (node: ts.Node): readonly string[] => {
+  if (ts.isSourceFile(node)) {
+    return [...importedLocals(node), ...declaredIn(node.statements), ...hoistedVars(node)];
+  }
+  if (ts.isBlock(node) || ts.isModuleBlock(node)) return declaredIn(node.statements);
+  if (ts.isCaseBlock(node)) return declaredIn(node.clauses.flatMap((c) => [...c.statements]));
+  if (ts.isCatchClause(node)) {
+    return node.variableDeclaration ? bindingNames(node.variableDeclaration.name) : [];
+  }
+  if (
+    (ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node)) &&
+    node.initializer &&
+    ts.isVariableDeclarationList(node.initializer)
+  ) {
+    return node.initializer.declarations.flatMap((d) => bindingNames(d.name));
+  }
+  if (ts.isFunctionLike(node)) {
+    const own =
+      (ts.isFunctionExpression(node) || ts.isClassExpression(node)) && node.name
+        ? [node.name.text]
+        : [];
+    return [...own, ...node.parameters.flatMap((p) => bindingNames(p.name)), ...hoistedVars(node)];
+  }
+  return [];
+};
+
+/** True when `name` resolves to a non-onrails binding at `node` (walks every enclosing scope). */
+const isShadowed = (node: ts.Node, name: string): boolean => {
+  for (let cur: ts.Node | undefined = node.parent; cur; cur = cur.parent) {
+    if (boundBy(cur).includes(name)) return true;
+  }
+  return false;
+};
+
+const PATTERN_CALLS = new Set(["with", "withEither", "when", "isMatching"]);
+
+/**
+ * True when the literal is (part of) a pattern argument of a ts-pattern style call. A pattern is
+ * not a value: `ok(P.number)` would be a carrier where a matcher is expected. Stops at function
+ * boundaries so literals inside a handler body are still rewritten.
+ */
+const isPatternPosition = (node: ts.Node): boolean => {
+  for (let cur: ts.Node | undefined = node.parent; cur; cur = cur.parent) {
+    if (ts.isFunctionLike(cur)) return false;
+    if (!ts.isCallExpression(cur)) continue;
+    const callee = cur.expression;
+    const name = ts.isPropertyAccessExpression(callee)
+      ? callee.name.text
+      : ts.isIdentifier(callee)
+        ? callee.text
+        : "";
+    if (PATTERN_CALLS.has(name)) return true;
+  }
+  return false;
+};
+
+/** The node to replace: the literal, widened over a trailing `as const` that the call makes redundant. */
+const spanNode = (lit: ts.ObjectLiteralExpression): ts.Node =>
+  ts.isAsExpression(lit.parent) &&
+  ts.isTypeReferenceNode(lit.parent.type) &&
+  lit.parent.type.typeName.getText() === "const"
+    ? lit.parent
+    : lit;
+
+const collectEdits = (src: string, jsx: boolean): readonly LiteralEdit[] => {
+  const edits: LiteralEdit[] = [];
+  walkSource(
+    src,
+    (node, sf) => {
+      if (!ts.isObjectLiteralExpression(node)) return false;
+      const props = readProps(node);
+      const tag = props && tagOf(props);
+      const shape = tag ? SHAPES[tag] : undefined;
+      if (!props || !shape || isShadowed(node, shape.fn) || isPatternPosition(node)) return false;
+      const wanted = shape.field === null ? ["_tag"] : ["_tag", shape.field];
+      const keys = props.map((p) => p.key);
+      if (keys.length !== wanted.length || !wanted.every((k) => keys.includes(k))) return false;
+      const arg =
+        shape.field === null ? "" : (props.find((p) => p.key === shape.field)?.text ?? "");
+      const span = spanNode(node);
+      edits.push({
+        start: span.getStart(sf),
+        end: span.getEnd(),
+        text: `${shape.fn}(${arg})`,
+        name: shape.fn,
+        spec: shape.spec,
+      });
+      // outermost only; nested literals are picked up on the next pass
+      return true;
+    },
+    jsx,
+  );
+  return edits;
+};
+
+const matchingImports = (sf: ts.SourceFile, spec: string): readonly ts.ImportDeclaration[] =>
+  sf.statements.filter(
+    (st): st is ts.ImportDeclaration =>
+      ts.isImportDeclaration(st) &&
+      ts.isStringLiteral(st.moduleSpecifier) &&
+      st.moduleSpecifier.text === spec &&
+      !st.importClause?.isTypeOnly &&
+      st.importClause?.namedBindings !== undefined &&
+      ts.isNamedImports(st.importClause.namedBindings),
+  );
+
+/**
+ * Merges `names` into a value import of `spec` (found through the parser), or inserts one after any
+ * shebang. A name counts as present only when a plain, unaliased, non-type specifier binds it locally.
+ */
+const addImports = (src: string, spec: string, names: readonly string[]): string => {
+  const wanted = [...new Set(names)].sort();
+  if (wanted.length === 0) return src;
+  const sf = ts.createSourceFile("codemod.ts", src, ts.ScriptTarget.Latest, true);
+  const decls = matchingImports(sf, spec);
+  const bound = new Set(
+    decls.flatMap((d) => {
+      const nb = d.importClause?.namedBindings;
+      return nb && ts.isNamedImports(nb)
+        ? nb.elements.filter((el) => isPlainValueSpecifier(el, false)).map((el) => el.name.text)
+        : [];
+    }),
+  );
+  const extra = wanted.filter((n) => !bound.has(n));
+  if (extra.length === 0) return src;
+  const target = decls[0]?.importClause?.namedBindings;
+  if (target && ts.isNamedImports(target)) {
+    // keep existing specifiers verbatim (`type X`, aliases) and append what is missing
+    const texts = [...target.elements.map((el) => el.getText(sf)), ...extra];
+    return `${src.slice(0, target.getStart(sf))}{ ${texts.join(", ")} }${src.slice(target.getEnd())}`;
+  }
+  const line = `import { ${extra.join(", ")} } from "${spec}";\n`;
+  const shebang = /^#![^\n]*\n/.exec(src);
+  return shebang ? `${shebang[0]}${line}${src.slice(shebang[0].length)}` : `${line}${src}`;
+};
+
+/** Rewrites `{ _tag: "Ok", value }` style literals to `ok(value)` etc. so carriers are built by constructors. */
+export function rewriteCarrierLiterals(src: string, jsx = false): string {
+  let cur = src;
+  const used = new Map<string, Set<string>>();
+  // each pass rewrites the outermost literals and strictly shrinks the literal count, so this terminates
+  for (;;) {
+    const edits = [...collectEdits(cur, jsx)].sort((a, b) => b.start - a.start);
+    if (edits.length === 0) break;
+    for (const e of edits) {
+      cur = `${cur.slice(0, e.start)}${e.text}${cur.slice(e.end)}`;
+      used.set(e.spec, (used.get(e.spec) ?? new Set()).add(e.name));
+    }
+  }
+  return [...used].reduce((acc, [spec, names]) => addImports(acc, spec, [...names]), cur);
+}

package/src/types.ts

@@ -1,4 +1,4 @@
-export type Mode = "compat" | "native" | "tersify";
+export type Mode = "compat" | "native" | "tersify" | "literals";
 export type Args = { target: string; dry: boolean; onrails: string; mode: Mode };
 
 export type Warning = { line: number; label: string; text: string };