@onrails/codemod 0.1.0 → 0.1.2

package/README.md

@@ -16,13 +16,20 @@ bunx @onrails/codemod /path/to/target-repo --dry
 
 ## What it does
 
-Rewrites every `from "neverthrow"` import and every `neverthrow` `package.json` dep to point at `@onrails/result/compat/neverthrow`.
+By default, rewrites every `from "neverthrow"` import and every `neverthrow`
+`package.json` dep to point at `@onrails/result/compat/neverthrow`.
 
 - Walks `.ts` / `.tsx` / `.mts` / `.cts`. Skips `node_modules`, `dist`, `.git`, `.next`, `.turbo`, `coverage`, `build`.
 - Rewrites only the specifier in `import` / `from` / `import(...)`; string mentions of `"neverthrow"` in regular code are left alone.
 - Updates `dependencies` / `devDependencies` / `peerDependencies` in every nested `package.json` that lists `neverthrow`, replacing it with `@onrails/result` at a path relative to that `package.json`.
 - Idempotent. Safe to re-run.
 
+With `--to-native`, rewrites safe `@onrails/result/compat/neverthrow`
+imports to native `@onrails/result` imports, then rewrites supported sync
+method chains to native `pipe(...)` calls. This mode also reports TODO lines
+for compat-only properties and unsupported import shapes that still need manual
+migration.
+
 ## Usage
 
 ```bash
@@ -35,6 +42,10 @@ bunx @onrails/codemod /path/to/target-repo
 # point at a local @onrails/result checkout (file: install)
 bunx @onrails/codemod /path/to/target-repo \
   --onrails=/Users/me/dev/onrails/packages/result
+
+# 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
 ```
 
 After applying:
@@ -47,10 +58,45 @@ bun typecheck
 bun test
 ```
 
+## Native migration
+
+`--to-native` is intentionally conservative. It rewrites imports that have a
+native equivalent:
+
+```ts
+import { ok, err, Result } from "@onrails/result/compat/neverthrow";
+```
+
+becomes:
+
+```ts
+import { ok, err } from "@onrails/result";
+import type { Result } from "@onrails/result";
+```
+
+It does not rewrite arbitrary method chains or namespace/re-export shapes yet.
+The CLI rewrites supported sync chains such as:
+
+```ts
+ok(1).map(double).andThen(validate).orElse(recoverInput);
+```
+
+to:
+
+```ts
+pipe(ok(1), map(double), flatMap(validate), recover(recoverInput));
+```
+
+Terminal `.match(...)` and `.unwrapOr(...)` become data-first native calls.
+`ResultAsync`-looking chains stay method-style because the native async API
+already supports those methods. The CLI still reports TODO lines for compat-only
+surface such as `.isOk()`, `.value`, `Result.fromThrowable(...)`,
+`import * as neverthrow from ...`, and `export { ok } from ...`.
+
 ## Roadmap
 
-- Stage-2 codemod (compat → native `@onrails/result` API): planned, not shipped. Tracking in the repo issues.
 - Generalized rename codemod (any `from "A"` → `from "B"` + deps): planned.
+- AST-backed compat method-chain rewrite to `pipe(...)` / `fluent(...)`: planned.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onrails/codemod",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Codemods for migrating onto @onrails/result (neverthrow → compat shim, and beyond)",
   "license": "MIT",
   "author": "Alan R. Soares",
@@ -41,7 +41,14 @@
   "exports": {
     ".": "./src/index.ts"
   },
+  "dependencies": {
+    "@onrails/maybe": "0.1.0",
+    "@onrails/pattern": "0.1.0",
+    "@onrails/result": "0.1.0",
+    "typescript": "^6.0.3"
+  },
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
   }
 }

package/src/ast.ts

@@ -0,0 +1,58 @@
+import { fromNullable, type Maybe, match as matchMaybe, none, some } from "@onrails/maybe";
+import ts from "typescript";
+import { TYPE_ONLY_NATIVE } from "./constants.js";
+import type { Edit } from "./types.js";
+
+export const edit = (text: string, imports: readonly string[] = []): Edit => ({
+  start: 0,
+  end: 0,
+  text,
+  imports,
+});
+
+export const lookupMap = <K, V, R>(m: Map<K, V>, k: K, f: (v: V) => R): Maybe<R> =>
+  matchMaybe(fromNullable(m.get(k)), (v) => some(f(v)), none);
+
+export const concatCollectors =
+  <T, R>(...fns: Array<(t: T) => readonly R[]>) =>
+  (t: T): readonly R[] =>
+    fns.flatMap((f) => f(t));
+
+export const walkSource = (
+  src: string,
+  visit: (node: ts.Node, sf: ts.SourceFile) => unknown,
+): void => {
+  const sf = ts.createSourceFile("codemod.ts", src, ts.ScriptTarget.Latest, true);
+  const go = (n: ts.Node) => {
+    if (visit(n, sf)) return;
+    ts.forEachChild(n, go);
+  };
+  go(sf);
+};
+
+export const spanEdit = (node: ts.Node, sf: ts.SourceFile, partial: Edit): Edit => ({
+  ...partial,
+  start: node.getStart(sf),
+  end: node.getEnd(),
+});
+
+export const argsToText = (args: ts.NodeArray<ts.Expression>): string =>
+  args.map((a) => a.getText()).join(", ");
+
+export const countOccurrences = (s: string, sub: string): number => s.split(sub).length - 1;
+
+export const splitImportNames = (specifiers: string): readonly string[] =>
+  specifiers
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+
+export const stripInlineType = (specifier: string): string => specifier.replace(/^type\s+/, "");
+
+export const importedName = (specifier: string): string =>
+  stripInlineType(specifier).split(/\s+as\s+/i)[0] ?? specifier;
+
+export const isTypeOnlyNative = (specifier: string): boolean =>
+  specifier.startsWith("type ") || TYPE_ONLY_NATIVE.has(importedName(specifier));
+
+export const isValueImport = (specifier: string): boolean => !isTypeOnlyNative(specifier);

package/src/chains.ts

@@ -0,0 +1,157 @@
+import { compactMap, isSome, type Maybe, none, some } from "@onrails/maybe";
+import ts from "typescript";
+import { argsToText, edit, lookupMap, spanEdit, walkSource } from "./ast.js";
+import {
+  ASYNC_ROOT_HINTS,
+  CHAIN_METHODS,
+  PREDICATE_METHODS,
+  RESULT_SPECIFIC_CHAIN_METHODS,
+  SAFE_BASE_PATTERNS,
+  TEE_METHODS,
+  TERMINAL_METHODS,
+  UNSAFE_UNWRAP_METHODS,
+  ZERO_ARG_HELPERS,
+} from "./constants.js";
+import { addNativeValueImports } from "./imports.js";
+import type { ChainStep, Edit, EditAcc, PipelinePart } from "./types.js";
+
+export function isSupportedChainCall(node: ts.Node): node is ts.CallExpression {
+  if (!ts.isCallExpression(node)) return false;
+  if (!ts.isPropertyAccessExpression(node.expression)) return false;
+  const method = node.expression.name.text;
+  return CHAIN_METHODS.has(method) || TERMINAL_METHODS.has(method);
+}
+
+export function helperCallToNative(node: ts.CallExpression): Maybe<Edit> {
+  if (ts.isIdentifier(node.expression) && node.arguments.length === 0) {
+    return lookupMap(ZERO_ARG_HELPERS, node.expression.text, (text) => edit(text));
+  }
+
+  if (!ts.isPropertyAccessExpression(node.expression)) return none();
+  const method = node.expression.name.text;
+  const base = node.expression.expression
+    .getText()
+    .replaceAll(".andTee(", ".tap(")
+    .replaceAll(".orTee(", ".tapErr(");
+  const argsText = argsToText(node.arguments);
+
+  const tee = lookupMap(TEE_METHODS, method, (t) => edit(`${base}.${t}(${argsText})`));
+  if (isSome(tee)) return tee;
+
+  if (PREDICATE_METHODS.has(method)) {
+    return some(edit(`${method}(${base})`, [method]));
+  }
+
+  return lookupMap(UNSAFE_UNWRAP_METHODS, method, (u) => edit(`${u}(${base})`, [u]));
+}
+
+export function isNestedInSupportedChain(node: ts.Node): boolean {
+  const parent = node.parent;
+  if (!parent) return false;
+  if (!ts.isPropertyAccessExpression(parent)) return false;
+  return isSupportedChainCall(parent.parent);
+}
+
+export function collectChain(node: ts.CallExpression): { base: string; steps: ChainStep[] } {
+  const steps: ChainStep[] = [];
+  let current: ts.Expression = node;
+
+  while (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+    const method = current.expression.name.text;
+    if (!CHAIN_METHODS.has(method) && !TERMINAL_METHODS.has(method)) break;
+    steps.push({
+      method,
+      argsText: argsToText(current.arguments),
+      argCount: current.arguments.length,
+    });
+    current = current.expression.expression;
+  }
+
+  return {
+    base: current.getText(),
+    steps: steps.reverse(),
+  };
+}
+
+export const hasAsyncRootHint = (base: string): boolean =>
+  ASYNC_ROOT_HINTS.some((hint) => base.includes(hint));
+
+export const isSafeSyncChainBase = (base: string): boolean =>
+  SAFE_BASE_PATTERNS.some((re) => re.test(base));
+
+const isTerminalStep = (s: ChainStep): boolean => TERMINAL_METHODS.has(s.method);
+const isResultSpecificStep = (s: ChainStep): boolean => RESULT_SPECIFIC_CHAIN_METHODS.has(s.method);
+const isChainStep = (s: ChainStep): boolean => CHAIN_METHODS.has(s.method);
+
+export function chainToNative(base: string, steps: readonly ChainStep[]): Maybe<Edit> {
+  if (steps.length === 0 || hasAsyncRootHint(base)) return none();
+  const terminalStep = steps.find(isTerminalStep);
+  if (!isSafeSyncChainBase(base)) return none();
+  if (!terminalStep && !steps.some(isResultSpecificStep)) return none();
+  if (terminalStep?.method === "match" && terminalStep.argCount !== 2) return none();
+  const pipelineSteps = steps.filter(isChainStep);
+  const pipelineParts = compactMap(pipelineSteps, (step) =>
+    lookupMap(
+      CHAIN_METHODS,
+      step.method,
+      (nativeName): PipelinePart => ({
+        importName: nativeName,
+        text: `${nativeName}(${step.argsText})`,
+      }),
+    ),
+  );
+
+  if (pipelineParts.length !== pipelineSteps.length) return none();
+
+  const parts = pipelineParts.map((part) => part.text);
+  const imports = new Set(pipelineParts.map((part) => part.importName));
+  const pipeline = parts.length > 0 ? `pipe(${[base, ...parts].join(", ")})` : base;
+
+  if (parts.length > 0) imports.add("pipe");
+
+  if (!terminalStep) {
+    return some(edit(pipeline, [...imports]));
+  }
+
+  imports.add(terminalStep.method);
+  return some(edit(`${terminalStep.method}(${pipeline}, ${terminalStep.argsText})`, [...imports]));
+}
+
+export const byStartDesc = (a: Edit, b: Edit): number => b.start - a.start;
+
+export const applyEditStep = (acc: EditAcc, e: Edit): EditAcc => ({
+  src: `${acc.src.slice(0, e.start)}${e.text}${acc.src.slice(e.end)}`,
+  imports: new Set([...acc.imports, ...e.imports]),
+});
+
+export function rewriteCompatMethodChainsToNative(src: string): string {
+  const edits: Edit[] = [];
+
+  walkSource(src, (node, sf) => {
+    if (ts.isCallExpression(node)) {
+      const helper = helperCallToNative(node);
+      if (isSome(helper)) {
+        edits.push(spanEdit(node, sf, helper.value));
+        return true;
+      }
+    }
+
+    if (
+      isSupportedChainCall(node) &&
+      !isNestedInSupportedChain(node) &&
+      !ts.isPropertyAccessExpression(node.parent)
+    ) {
+      const chain = collectChain(node);
+      const chained = chainToNative(chain.base, chain.steps);
+      if (isSome(chained)) edits.push(spanEdit(node, sf, chained.value));
+    }
+  });
+
+  if (edits.length === 0) return src;
+
+  const { src: next, imports } = edits
+    .sort(byStartDesc)
+    .reduce(applyEditStep, { src, imports: new Set<string>() });
+
+  return addNativeValueImports(next, [...imports]);
+}

package/src/cli.ts

@@ -0,0 +1,132 @@
+import { relative, resolve } from "node:path";
+import { type Maybe, match as matchMaybe, none, some, tap } from "@onrails/maybe";
+import { match } from "@onrails/pattern";
+import { err, isErr, ok, type Result, ResultAsync } from "@onrails/result";
+import { Glob } from "bun";
+import { CODE_EXT, SKIP } from "./constants.js";
+import { computeFileChange, toFileChange } from "./file-change.js";
+import { readFileText, writeFileText } from "./io.js";
+import { rewritePkg } from "./pkg.js";
+import type { ArgState, Args, FileChange, Mode, PkgChange } from "./types.js";
+
+const ONRAILS_FLAG = "--onrails=";
+
+const applyArg = (s: ArgState, a: string): ArgState =>
+  match(a)
+    .returnType<ArgState>()
+    .withEither("--dry", "-n", () => ({ ...s, dry: true }))
+    .with("--to-native", () => ({ ...s, mode: "native" }))
+    .with(
+      (x) => x.startsWith(ONRAILS_FLAG),
+      (x) => ({ ...s, onrails: resolve(x.slice(ONRAILS_FLAG.length)) }),
+    )
+    .with(
+      (x) => !x.startsWith("--"),
+      (x) => ({ ...s, positional: [...s.positional, x] }),
+    )
+    .otherwise(() => s);
+
+const USAGE =
+  "usage: onrails-codemod-neverthrow <target-dir> [--dry] [--to-native] [--onrails=<abs-path>]";
+
+export function parseArgs(argv: string[]): Result<Args, string> {
+  const initial: ArgState = {
+    positional: [],
+    dry: false,
+    mode: "compat",
+    onrails: resolve(import.meta.dir, "../../..", "packages/result"),
+  };
+  const { positional, dry, mode, onrails } = argv.reduce(applyArg, initial);
+  if (positional.length !== 1) {
+    return err(USAGE);
+  }
+  return ok({
+    target: resolve(positional[0] ?? "."),
+    dry,
+    onrails,
+    mode,
+  });
+}
+
+const shouldSkip = (path: string) => path.split("/").some((seg) => SKIP.has(seg));
+
+async function* walk(root: string): AsyncGenerator<string> {
+  const glob = new Glob("**/*");
+  for await (const rel of glob.scan({ cwd: root, dot: false, onlyFiles: true })) {
+    if (!shouldSkip(rel)) yield `${root}/${rel}`;
+  }
+}
+
+const rewriteCode = (
+  path: string,
+  dry: boolean,
+  mode: Mode,
+): ResultAsync<Maybe<FileChange>, Error> =>
+  readFileText(path).flatMap((src) =>
+    matchMaybe(
+      computeFileChange(src, mode),
+      (c) => {
+        const change = toFileChange(path, c);
+        return c.changed && !dry
+          ? writeFileText(path, c.next).map(() => some(change))
+          : ResultAsync.ok<Maybe<FileChange>, Error>(some(change));
+      },
+      () => ResultAsync.ok<Maybe<FileChange>, Error>(none()),
+    ),
+  );
+
+const collectInto =
+  <T>(into: T[], file: string) =>
+  (r: ResultAsync<Maybe<T>, Error>): Promise<void> =>
+    r.match(
+      (m) => void tap(m, (c) => into.push(c)),
+      (e) => console.error(`error processing ${file}:`, e.message),
+    );
+
+const printReport = (
+  { target, dry, onrails, mode }: Args,
+  codeChanges: readonly FileChange[],
+  pkgChanges: readonly PkgChange[],
+): void => {
+  const label = dry ? "DRY" : "APPLY";
+  console.log(`[${label}] target=${target}`);
+  console.log(`[${label}] mode=${mode}`);
+  if (mode === "compat") console.log(`[${label}] onrails=${onrails}`);
+  const changedCodeCount = codeChanges.filter((c) => c.changed).length;
+  console.log(`[${label}] code files changed: ${changedCodeCount}`);
+  if (mode === "native") {
+    console.log(`[${label}] code files reported only: ${codeChanges.length - changedCodeCount}`);
+  }
+  for (const c of codeChanges) {
+    console.log(`  ${relative(target, c.path)}  (${c.before} import${c.before === 1 ? "" : "s"})`);
+    for (const warning of c.warnings) {
+      console.log(`    TODO line ${warning.line}: ${warning.label}: ${warning.text}`);
+    }
+  }
+  if (mode === "compat") {
+    console.log(`[${label}] package.json updated: ${pkgChanges.length}`);
+    for (const c of pkgChanges) {
+      console.log(`  ${relative(target, c.path)}  [${c.removed.join(", ")}] -> ${c.addedAs}`);
+    }
+  }
+  if (dry) console.log(`[${label}] no files written. re-run without --dry to apply.`);
+};
+
+export async function main() {
+  const parsed = parseArgs(Bun.argv.slice(2));
+  if (isErr(parsed)) {
+    console.error(parsed.error);
+    process.exit(2);
+  }
+  const args = parsed.value;
+  const { target, dry, onrails, mode } = args;
+  const codeChanges: FileChange[] = [];
+  const pkgChanges: PkgChange[] = [];
+  for await (const file of walk(target)) {
+    if (mode === "compat" && file.endsWith("/package.json"))
+      await collectInto(pkgChanges, file)(rewritePkg(file, onrails, dry));
+    else if (CODE_EXT.test(file))
+      await collectInto(codeChanges, file)(rewriteCode(file, dry, mode));
+  }
+  printReport(args, codeChanges, pkgChanges);
+}

package/src/constants.ts

@@ -0,0 +1,63 @@
+export const SKIP = new Set([
+  "node_modules",
+  "dist",
+  ".git",
+  ".next",
+  ".turbo",
+  "coverage",
+  "build",
+]);
+export const CODE_EXT = /\.(ts|tsx|mts|cts)$/;
+export const IMPORT_RE = /(from\s+|import\s*\(\s*)(['"])neverthrow\2/g;
+export const COMPAT_SPEC = "@onrails/result/compat/neverthrow";
+export const NATIVE_SPEC = "@onrails/result";
+export const DEP_KEYS = ["dependencies", "devDependencies", "peerDependencies"] as const;
+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" },
+] as const;
+export const RESULT_SPECIFIC_CHAIN_METHODS = new Set([
+  "andThen",
+  "chain",
+  "flatMap",
+  "mapErr",
+  "orElse",
+  "recover",
+  "tapErr",
+  "match",
+  "unwrapOr",
+]);
+export const CHAIN_METHODS = new Map([
+  ["map", "map"],
+  ["mapErr", "mapErr"],
+  ["andThen", "flatMap"],
+  ["chain", "flatMap"],
+  ["flatMap", "flatMap"],
+  ["orElse", "recover"],
+  ["recover", "recover"],
+  ["tap", "tap"],
+  ["tapErr", "tapErr"],
+]);
+export const TERMINAL_METHODS = new Set(["match", "unwrapOr"]);
+export const ASYNC_ROOT_HINTS = [
+  "ResultAsync",
+  "okAsync",
+  "errAsync",
+  "fromPromise",
+  "fromSafePromise",
+];
+export const ZERO_ARG_HELPERS = new Map([
+  ["ok", "ok(undefined)"],
+  ["okAsync", "okAsync(undefined)"],
+]);
+export const TEE_METHODS = new Map([
+  ["andTee", "tap"],
+  ["orTee", "tapErr"],
+]);
+export const PREDICATE_METHODS = new Set(["isOk", "isErr"]);
+export const UNSAFE_UNWRAP_METHODS = new Map([
+  ["_unsafeUnwrap", "unwrapOk"],
+  ["_unsafeUnwrapErr", "unwrapErr"],
+]);
+export const SAFE_BASE_PATTERNS = [/^(ok|err)\s*\(/, /^Result\./, /^[a-zA-Z_$][\w$]*$/] as const;

package/src/file-change.ts

@@ -0,0 +1,57 @@
+import { type Maybe, none, some } from "@onrails/maybe";
+import { flow } from "@onrails/result";
+import { concatCollectors, 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 type { ComputedChange, FileChange, Mode, ModeStrategy } from "./types.js";
+import {
+  collectNativeMigrationWarnings,
+  collectUnsupportedCompatImportWarnings,
+} from "./warnings.js";
+
+const rewriteCompatToNative = flow(rewriteCompatImportsToNative, rewriteCompatMethodChainsToNative);
+
+const rewriteNeverthrowToCompat = (src: string): string =>
+  src.replace(IMPORT_RE, (_, lead, quote) => `${lead}${quote}${COMPAT_SPEC}${quote}`);
+
+const collectAllNativeWarnings = concatCollectors(
+  collectUnsupportedCompatImportWarnings,
+  collectNativeMigrationWarnings,
+);
+
+const MODES: Record<Mode, ModeStrategy> = {
+  compat: {
+    countBefore: (src) => (src.match(IMPORT_RE) ?? []).length,
+    earlyExit: (_src, before) => before === 0,
+    transform: rewriteNeverthrowToCompat,
+    warnings: () => [],
+    countAfter: () => 0,
+  },
+  native: {
+    countBefore: (src) => countOccurrences(src, COMPAT_SPEC),
+    earlyExit: () => false,
+    transform: rewriteCompatToNative,
+    warnings: collectAllNativeWarnings,
+    countAfter: (next) => countOccurrences(next, NATIVE_SPEC),
+  },
+};
+
+export const computeFileChange = (src: string, mode: Mode): Maybe<ComputedChange> => {
+  const strat = MODES[mode];
+  const before = strat.countBefore(src);
+  if (strat.earlyExit(src, before)) return none();
+  const next = strat.transform(src);
+  const changed = next !== src;
+  const warnings = strat.warnings(next);
+  if (!changed && warnings.length === 0) return none();
+  return some({ next, before, after: strat.countAfter(next), changed, warnings });
+};
+
+export const toFileChange = (path: string, c: ComputedChange): FileChange => ({
+  path,
+  before: c.before,
+  after: c.after,
+  changed: c.changed,
+  warnings: c.warnings,
+});

package/src/imports.ts

@@ -0,0 +1,56 @@
+import { isTypeOnlyNative, isValueImport, splitImportNames, stripInlineType } from "./ast.js";
+import { COMPAT_SPEC, NATIVE_SPEC } from "./constants.js";
+
+export function toNativeImport(full: string, specifiers: string, quote: string): string {
+  const imports = splitImportNames(specifiers);
+  const typeNames = imports.filter(isTypeOnlyNative).map(stripInlineType);
+  const valueNames = imports.filter(isValueImport);
+  const chunks: string[] = [];
+
+  if (valueNames.length > 0) {
+    chunks.push(`import { ${valueNames.join(", ")} } from ${quote}${NATIVE_SPEC}${quote};`);
+  }
+
+  if (typeNames.length > 0) {
+    chunks.push(`import type { ${typeNames.join(", ")} } from ${quote}${NATIVE_SPEC}${quote};`);
+  }
+
+  return chunks.length > 0 ? chunks.join("\n") : full;
+}
+
+export function rewriteCompatImportsToNative(src: string): string {
+  const namedImportRe = new RegExp(
+    String.raw`import\s+\{\s*([^}]+?)\s*\}\s+from\s+(['"])${COMPAT_SPEC.replaceAll("/", String.raw`\/`)}\2\s*;?`,
+    "g",
+  );
+  const typeNamedImportRe = new RegExp(
+    String.raw`import\s+type\s+\{\s*([^}]+?)\s*\}\s+from\s+(['"])${COMPAT_SPEC.replaceAll("/", String.raw`\/`)}\2\s*;?`,
+    "g",
+  );
+
+  return src
+    .replace(typeNamedImportRe, (_full, specifiers: string, quote: string) => {
+      const imports = splitImportNames(specifiers);
+      return `import type { ${imports.join(", ")} } from ${quote}${NATIVE_SPEC}${quote};`;
+    })
+    .replace(namedImportRe, (full: string, specifiers: string, quote: string) =>
+      toNativeImport(full, specifiers, quote),
+    );
+}
+
+export function addNativeValueImports(src: string, imports: readonly string[]): string {
+  const names = [...new Set(imports)].sort();
+  if (names.length === 0) return src;
+  const importRe = new RegExp(
+    String.raw`import\s+\{\s*([^}]*?)\s*\}\s+from\s+(['"])${NATIVE_SPEC.replaceAll("/", String.raw`\/`)}\2\s*;?`,
+  );
+  const match = importRe.exec(src);
+
+  if (!match?.[1]) {
+    return `import { ${names.join(", ")} } from "${NATIVE_SPEC}";\n${src}`;
+  }
+
+  const existing = splitImportNames(match[1]).map(stripInlineType);
+  const next = [...new Set([...existing, ...names])].sort();
+  return `${src.slice(0, match.index)}import { ${next.join(", ")} } from ${match[2]}${NATIVE_SPEC}${match[2]};${src.slice(match.index + match[0].length)}`;
+}

package/src/index.ts

@@ -1,137 +1,11 @@
 #!/usr/bin/env bun
-import { relative, resolve } from "node:path";
-/**
- * Codemod: migrate `neverthrow` imports + package.json deps to
- * `@onrails/result/compat/neverthrow`.
- *
- * Usage:
- *   bun run packages/result/scripts/codemod-neverthrow.ts <target-dir> [--dry] [--onrails=<abs-path>]
- *
- * - Rewrites import specifiers `"neverthrow"` -> `"@onrails/result/compat/neverthrow"`
- *   in `.ts` / `.tsx` / `.mts` / `.cts` files.
- * - Updates every `package.json` that lists `neverthrow` under
- *   `dependencies` / `devDependencies` / `peerDependencies`:
- *     - removes the `neverthrow` entry
- *     - adds `@onrails/result` with a `file:` path relative to the package.json
- * - Skips `node_modules`, `dist`, `.git`, `.next`, `.turbo`, `coverage`.
- * - Idempotent. Safe to re-run.
- */
-import { Glob } from "bun";
+import { main } from "./cli.js";
 
-type Args = { target: string; dry: boolean; onrails: string };
+export { rewriteCompatMethodChainsToNative } from "./chains.js";
+export { main } from "./cli.js";
+export { computeFileChange } from "./file-change.js";
+export { rewriteCompatImportsToNative } from "./imports.js";
+export { computePkgRewrite } from "./pkg.js";
+export { collectNativeMigrationWarnings } from "./warnings.js";
 
-const SKIP = new Set(["node_modules", "dist", ".git", ".next", ".turbo", "coverage", "build"]);
-const CODE_EXT = /\.(ts|tsx|mts|cts)$/;
-const IMPORT_RE = /(from\s+|import\s*\(\s*)(['"])neverthrow\2/g;
-const NEW_SPEC = "@onrails/result/compat/neverthrow";
-const DEP_KEYS = ["dependencies", "devDependencies", "peerDependencies"] as const;
-
-function parseArgs(argv: string[]): Args {
-  const positional: string[] = [];
-  let dry = false;
-  let onrails = resolve(import.meta.dir, "../../..", "packages/result");
-  for (const a of argv) {
-    if (a === "--dry" || a === "-n") dry = true;
-    else if (a.startsWith("--onrails=")) onrails = resolve(a.slice("--onrails=".length));
-    else if (!a.startsWith("--")) positional.push(a);
-  }
-  if (positional.length !== 1) {
-    console.error(
-      "usage: bun run codemod-neverthrow.ts <target-dir> [--dry] [--onrails=<abs-path>]",
-    );
-    process.exit(2);
-  }
-  return { target: resolve(positional[0] ?? "."), dry, onrails };
-}
-
-function shouldSkip(path: string): boolean {
-  return path.split("/").some((seg) => SKIP.has(seg));
-}
-
-async function* walk(root: string): AsyncGenerator<string> {
-  const glob = new Glob("**/*");
-  for await (const rel of glob.scan({ cwd: root, dot: false, onlyFiles: true })) {
-    if (!shouldSkip(rel)) yield `${root}/${rel}`;
-  }
-}
-
-type FileChange = { path: string; before: number; after: number };
-
-async function rewriteCode(path: string, dry: boolean): Promise<FileChange | null> {
-  const src = await Bun.file(path).text();
-  if (!src.includes("neverthrow")) return null;
-  const before = (src.match(IMPORT_RE) ?? []).length;
-  if (before === 0) return null;
-  const next = src.replace(IMPORT_RE, (_, lead, quote) => `${lead}${quote}${NEW_SPEC}${quote}`);
-  if (next === src) return null;
-  if (!dry) await Bun.write(path, next);
-  return { path, before, after: 0 };
-}
-
-type PkgChange = { path: string; removed: string[]; addedAs: string };
-
-function reorderDeps(deps: Record<string, string>): Record<string, string> {
-  return Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)));
-}
-
-async function rewritePkg(
-  path: string,
-  onrailsAbs: string,
-  dry: boolean,
-): Promise<PkgChange | null> {
-  const raw = await Bun.file(path).text();
-  let json: Record<string, unknown>;
-  try {
-    json = JSON.parse(raw) as Record<string, unknown>;
-  } catch {
-    return null;
-  }
-  const removed: string[] = [];
-  let touched = false;
-  const pkgDir = path.replace(/\/package\.json$/, "");
-  const filePath = relative(pkgDir, onrailsAbs);
-  const fileSpec = `file:${filePath}`;
-  for (const key of DEP_KEYS) {
-    const deps = json[key] as Record<string, string> | undefined;
-    if (!deps || typeof deps !== "object") continue;
-    if (!("neverthrow" in deps)) continue;
-    delete deps.neverthrow;
-    removed.push(key);
-    deps["@onrails/result"] = fileSpec;
-    json[key] = reorderDeps(deps);
-    touched = true;
-  }
-  if (!touched) return null;
-  const out = `${JSON.stringify(json, null, 2)}\n`;
-  if (!dry) await Bun.write(path, out);
-  return { path, removed, addedAs: fileSpec };
-}
-
-async function main() {
-  const { target, dry, onrails } = parseArgs(Bun.argv.slice(2));
-  const codeChanges: FileChange[] = [];
-  const pkgChanges: PkgChange[] = [];
-  for await (const file of walk(target)) {
-    if (file.endsWith("/package.json")) {
-      const c = await rewritePkg(file, onrails, dry);
-      if (c) pkgChanges.push(c);
-    } else if (CODE_EXT.test(file)) {
-      const c = await rewriteCode(file, dry);
-      if (c) codeChanges.push(c);
-    }
-  }
-  const label = dry ? "DRY" : "APPLY";
-  console.log(`[${label}] target=${target}`);
-  console.log(`[${label}] onrails=${onrails}`);
-  console.log(`[${label}] code files rewritten: ${codeChanges.length}`);
-  for (const c of codeChanges) {
-    console.log(`  ${relative(target, c.path)}  (${c.before} import${c.before === 1 ? "" : "s"})`);
-  }
-  console.log(`[${label}] package.json updated: ${pkgChanges.length}`);
-  for (const c of pkgChanges) {
-    console.log(`  ${relative(target, c.path)}  [${c.removed.join(", ")}] -> ${c.addedAs}`);
-  }
-  if (dry) console.log(`[${label}] no files written. re-run without --dry to apply.`);
-}
-
-await main();
+if (import.meta.main) await main();

package/src/io.ts

@@ -0,0 +1,10 @@
+import { ResultAsync } from "@onrails/result";
+
+export const toError = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));
+
+export const readFileText = (path: string): ResultAsync<string, Error> =>
+  ResultAsync.fromPromise(Bun.file(path).text(), toError);
+
+export const writeFileText = (path: string, content: string): ResultAsync<unknown, Error> =>
+  ResultAsync.fromPromise(Bun.write(path, content), toError);

package/src/pkg.ts

@@ -0,0 +1,62 @@
+import { relative } from "node:path";
+import { type Maybe, match as matchMaybe, none, some } from "@onrails/maybe";
+import { type Result, ResultAsync, trySync } from "@onrails/result";
+import { DEP_KEYS } from "./constants.js";
+import { readFileText, toError, writeFileText } from "./io.js";
+import type { ComputedPkg, PkgChange, PkgUpdate } from "./types.js";
+
+const reorderDeps = (deps: Record<string, string>): Record<string, string> =>
+  Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)));
+
+export const parsePackageJson = (raw: string): Result<Record<string, unknown>, Error> =>
+  trySync(() => JSON.parse(raw) as Record<string, unknown>, toError)();
+
+const applyDepRewrite =
+  (fileSpec: string) =>
+  (acc: PkgUpdate, key: string): PkgUpdate => {
+    const deps = acc.json[key] as Record<string, string> | undefined;
+    if (!deps || typeof deps !== "object" || !("neverthrow" in deps)) return acc;
+    const { neverthrow: _drop, ...rest } = deps;
+    return {
+      json: { ...acc.json, [key]: reorderDeps({ ...rest, "@onrails/result": fileSpec }) },
+      removed: [...acc.removed, key],
+    };
+  };
+
+export const computePkgRewrite = (
+  json: Record<string, unknown>,
+  path: string,
+  onrailsAbs: string,
+): Maybe<ComputedPkg> => {
+  const fileSpec = `file:${relative(path.replace(/\/package\.json$/, ""), onrailsAbs)}`;
+  const updated = DEP_KEYS.reduce(applyDepRewrite(fileSpec), { json, removed: [] } as PkgUpdate);
+  return updated.removed.length === 0
+    ? none()
+    : some({ json: updated.json, removed: updated.removed, fileSpec });
+};
+
+const toPkgChange = (path: string, c: ComputedPkg): PkgChange => ({
+  path,
+  removed: [...c.removed],
+  addedAs: c.fileSpec,
+});
+
+export const rewritePkg = (
+  path: string,
+  onrailsAbs: string,
+  dry: boolean,
+): ResultAsync<Maybe<PkgChange>, Error> =>
+  readFileText(path)
+    .flatMap((raw) => ResultAsync.fromResult(parsePackageJson(raw)))
+    .flatMap((json) =>
+      matchMaybe(
+        computePkgRewrite(json, path, onrailsAbs),
+        (c) => {
+          const change = toPkgChange(path, c);
+          return dry
+            ? ResultAsync.ok<Maybe<PkgChange>, Error>(some(change))
+            : writeFileText(path, `${JSON.stringify(c.json, null, 2)}\n`).map(() => some(change));
+        },
+        () => ResultAsync.ok<Maybe<PkgChange>, Error>(none()),
+      ),
+    );

package/src/types.ts

@@ -0,0 +1,46 @@
+export type Mode = "compat" | "native";
+export type Args = { target: string; dry: boolean; onrails: string; mode: Mode };
+
+export type Warning = { line: number; label: string; text: string };
+export type FileChange = {
+  path: string;
+  before: number;
+  after: number;
+  changed: boolean;
+  warnings: readonly Warning[];
+};
+export type Edit = { start: number; end: number; text: string; imports: readonly string[] };
+export type ChainStep = { method: string; argsText: string; argCount: number };
+export type PipelinePart = { importName: string; text: string };
+
+export type ComputedChange = {
+  next: string;
+  before: number;
+  after: number;
+  changed: boolean;
+  warnings: readonly Warning[];
+};
+
+export type ModeStrategy = {
+  countBefore: (src: string) => number;
+  earlyExit: (src: string, before: number) => boolean;
+  transform: (src: string) => string;
+  warnings: (next: string) => readonly Warning[];
+  countAfter: (next: string) => number;
+};
+
+export type PkgChange = { path: string; removed: string[]; addedAs: string };
+export type PkgUpdate = { json: Record<string, unknown>; removed: readonly string[] };
+export type ComputedPkg = {
+  json: Record<string, unknown>;
+  removed: readonly string[];
+  fileSpec: string;
+};
+
+export type ArgState = {
+  positional: readonly string[];
+  dry: boolean;
+  mode: Mode;
+  onrails: string;
+};
+export type EditAcc = { src: string; imports: Set<string> };

package/src/warnings.ts

@@ -0,0 +1,61 @@
+import ts from "typescript";
+import { concatCollectors, walkSource } from "./ast.js";
+import { COMPAT_ONLY_PATTERNS, COMPAT_SPEC } from "./constants.js";
+import type { Warning } from "./types.js";
+
+export const collectRegexLineWarnings = (src: string): readonly Warning[] =>
+  src
+    .split(/\r?\n/)
+    .flatMap((line, i) =>
+      COMPAT_ONLY_PATTERNS.flatMap(({ pattern, label }) =>
+        pattern.test(line) ? [{ line: i + 1, label, text: line.trim() }] : [],
+      ),
+    );
+
+export const collectAstCompatWarnings = (src: string): readonly Warning[] => {
+  const warnings: Warning[] = [];
+  const lines = src.split(/\r?\n/);
+  const lineTextAt = (sf: ts.SourceFile, node: ts.Node) => {
+    const line = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+    return { line, text: lines[line - 1]?.trim() ?? node.getText(sf) };
+  };
+
+  walkSource(src, (node, sf) => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+      const method = node.expression.name.text;
+      if (method === "isOk" || method === "isErr") {
+        warnings.push({ ...lineTextAt(sf, node), label: "compat predicate method" });
+      }
+    }
+
+    if (ts.isPropertyAccessExpression(node)) {
+      const property = node.name.text;
+      if (property === "value" || property === "error") {
+        const receiver = node.expression.getText(sf);
+        if (/result$/i.test(receiver) || /^result$/i.test(receiver)) {
+          warnings.push({ ...lineTextAt(sf, node), label: "compat value/error property" });
+        }
+      }
+    }
+  });
+
+  return warnings;
+};
+
+export const collectNativeMigrationWarnings = concatCollectors(
+  collectRegexLineWarnings,
+  collectAstCompatWarnings,
+);
+
+export const collectUnsupportedCompatImportWarnings = (src: string): readonly Warning[] =>
+  src.split(/\r?\n/).flatMap((line, i) =>
+    line.includes(COMPAT_SPEC)
+      ? [
+          {
+            line: i + 1,
+            label: "unsupported compat import",
+            text: line.trim(),
+          },
+        ]
+      : [],
+  );