@arcgis/codemod 5.0.0-next.162

package/LICENSE.md

@@ -0,0 +1,17 @@
+# Licensing
+
+COPYRIGHT © Esri
+
+All rights reserved under the copyright laws of the United States and applicable international laws, treaties, and conventions.
+
+This material is licensed for use under the [Esri Master License Agreement (MLA)](https://www.esri.com/content/dam/esrisites/en-us/media/legal/ma-full/ma-full.pdf), and is bound by the terms of that agreement.
+You may redistribute and use this code without modification, provided you adhere to the terms of the MLA and include this copyright notice.
+
+For additional information, contact:
+Environmental Systems Research Institute, Inc.
+Attn: Contracts and Legal Services Department
+380 New York Street
+Redlands, California, USA 92373
+USA
+
+email: legal@esri.com

package/README.md

@@ -0,0 +1,78 @@
+# @arcgis/codemod
+
+A codemod toolkit for updating and modernizing ArcGIS Maps SDK for JavaScript codebases.
+
+This package provides automated refactors to help migrate away from deprecated or legacy patterns. Starting with removing the `__esri` namespace in TypeScript projects and replacing it with explicit imports.
+
+## Features
+
+- Automated refactor to remove `__esri` namespace usage
+- Converts global namespace types to explicit `@arcgis/core` imports
+- Detects edge cases and warns when changes can’t be safely automated
+- Respects `.gitignore` by default
+
+## Requirements
+
+- Node.js 24
+- A project using the ArcGIS Maps SDK for JavaScript
+- This codemod operates exclusively on TypeScript files. Do not need to run this tool, if the project does not use TypeScript.
+
+## Usage
+
+The codemod replaces `__esri` types with explicit imports from @arcgis/core.
+
+> Note: Before running the codemod, update all `@arcgis/*` packages in your `package.json` to the most recent version.
+
+Run it in the root of your project:
+
+```sh
+npx @arcgis/codemod run refactor-out-esri-namespace
+```
+
+By default, the codemod runs on all TypeScript files in the current directory and subdirectories, excluding files ignored by your `.gitignore`.
+You can manually run it on a different directory by providing an argument:
+
+```sh
+npx @arcgis/codemod run refactor-out-esri-namespace target-directory
+```
+
+### What codemod does
+
+**Before:**
+
+```tsx
+let geometry: __esri.Geometry;
+let featureSet: __esri.FeatureSet;
+```
+
+**After:**
+
+```tsx
+import type Geometry from "@arcgis/core/geometry/Geometry";
+import type FeatureSet from "@arcgis/core/rest/support/FeatureSet";
+
+let geometry: Geometry;
+
+let featureSet: FeatureSet;
+```
+
+### Warnings (Manual review required)
+
+The codemod will emit warnings for cases it cannot safely rewrite, including:
+
+- `__esri` references inside JSDoc comments
+- Complex computed or dynamic type usage
+- Unresolvable symbols
+
+These will be reported in the console, manually review all changes before committing.
+If your project uses **ESLint, Prettier, or other formatters/linters**, run them after the codemod to ensure consistent formatting.
+
+> Note: This codemod modifies files in place and does not provide an interactive dry-run mode. We recommend running it in a project that is under version control (Git) so you can review changes using `git diff` or your IDE’s diff tools. If your project is not under version control, create a backup before running the codemod.
+
+## License
+
+COPYRIGHT Esri
+
+This package is licensed under the terms described in the `LICENSE.md` file, located in the root of the package, and at https://js.arcgis.com/5.0/LICENSE.txt.
+
+For third party notices, see https://js.arcgis.com/5.0/third-party-notices.txt.

package/dist/cli-DB4-Ai2J.js

@@ -0,0 +1,256 @@
+import { log as h } from "@arcgis/toolkit/log";
+import { Command as $ } from "@commander-js/extra-typings";
+import { statSync as K } from "node:fs";
+import { getCwd as I, path as e, existsAsync as U, gitIgnoreFileToGlobs as L, asyncFindPath as E, toPosixPathSeparators as N, asyncRetrievePackageJson as J } from "@arcgis/components-build-utils";
+import "ts-morph";
+import i from "typescript";
+import { glob as _ } from "tinyglobby";
+import { identity as W } from "@arcgis/toolkit/function";
+import { styleText as B } from "node:util";
+const q = (t, o, n) => {
+  const r = t[o];
+  return r ? typeof r == "function" ? r() : Promise.resolve(r) : new Promise((a, c) => {
+    (typeof queueMicrotask == "function" ? queueMicrotask : setTimeout)(c.bind(null, /* @__PURE__ */ new Error("Unknown variable dynamic import: " + o + (o.split("/").length !== n ? ". Note that variables only represent file names one level deep." : ""))));
+  });
+}, ge = {
+  allowImportingTsExtensions: !0,
+  allowJs: !0,
+  allowArbitraryExtensions: !0,
+  allowSyntheticDefaultImports: !0,
+  checkJs: !0,
+  experimentalDecorators: !0,
+  forceConsistentCasingInFileNames: !1,
+  isolatedModules: !1,
+  isolatedDeclarations: !1,
+  jsx: i.JsxEmit.Preserve,
+  lib: ["lib.esnext.d.ts", "lib.dom.d.ts"],
+  module: i.ModuleKind.ESNext,
+  moduleResolution: i.ModuleResolutionKind.Bundler,
+  moduleDetection: i.ModuleDetectionKind.Auto,
+  strict: !1,
+  target: i.ScriptTarget.ESNext,
+  resolveJsonModule: !0,
+  esModuleInterop: !0
+}, j = {
+  codemod: void 0,
+  codemodName: void 0,
+  projectsData: void 0,
+  project: void 0
+};
+async function z() {
+  const { ignorePatterns: t, globRoot: o } = await H(), n = await Q(o);
+  return t.push(...n), { ignorePatterns: t, globRoot: o };
+}
+async function H() {
+  const t = [];
+  let o, n = I(), r = e.dirname(n);
+  do {
+    o = r;
+    const a = e.join(o, ".gitignore");
+    if (await U(a)) {
+      n = e.dirname(a);
+      const w = e.relative(n, I()).split("/"), y = L(a);
+      for (const f of y) {
+        const m = (f.startsWith("!") ? f.slice(1) : f).split("*")[0].split("/");
+        let p = !0;
+        for (let g = 0; g < m.length; g++)
+          if (w[g] !== m[g] && m[g] !== "") {
+            p = !1;
+            break;
+          }
+        p && (f.startsWith("!") || t.push(f));
+      }
+    }
+    r = e.dirname(o);
+  } while (r !== o);
+  return { ignorePatterns: t, globRoot: n };
+}
+async function Q(t) {
+  return (await _("**/.gitignore", {
+    // Gitignore files are unlikely to be symbolic links
+    followSymbolicLinks: !1,
+    // Don't look for ignore files in these places for speed:
+    ignore: [
+      // Hardcoded ignores in TypeScript
+      "**/node_modules/**",
+      "**/bower_components/**",
+      "**/jspm_packages/**",
+      // Default build output folder in bundlers
+      "**/dist/**"
+    ],
+    // Not applicable for our glob pattern
+    expandDirectories: !1
+  })).flatMap((n) => {
+    const r = e.relative(t, e.dirname(n)), a = L(n), c = [];
+    for (const w of a)
+      w.startsWith("!") || c.push(e.join(r, w));
+    return c;
+  });
+}
+const V = ["js", "jsx", "mjs", "cjs"], X = ["ts", "tsx", "mts", "cts"], Y = ["json"], Z = `**/*.{${[...V, ...X, ...Y].join(",")}}`;
+async function ee() {
+  const t = await z(), o = e.join(process.cwd(), Z), n = await _(o, {
+    cwd: t.globRoot,
+    ignore: t.ignorePatterns,
+    // The files we are looking for are unlikely to be symbolic links
+    followSymbolicLinks: !1,
+    // Not applicable for our glob pattern
+    expandDirectories: !1
+    // Files and folders starting with . are excluded (matches TypeScript's
+    // default behavior). If any tsconfig.json explicitly includes such files,
+    // they will still be codemodded.
+  });
+  let r = e.relative(t.globRoot, process.cwd());
+  r !== "" && (r += "/");
+  const a = e.join(e.resolve(t.globRoot), "/"), c = a.length + r.length, w = [], y = [], f = /* @__PURE__ */ new Set();
+  for (const s of n) {
+    const l = a + s;
+    if (s.endsWith(".json")) {
+      const d = e.basename(s);
+      d === "package.json" ? w.push(l) : (d.startsWith("tsconfig.") || d.startsWith("jsconfig.")) && y.push(l);
+    } else {
+      const d = s.slice(r.length);
+      f.add(d);
+    }
+  }
+  let v = await E("tsconfig.json", e.dirname(process.cwd()));
+  v !== void 0 && (v = N(v), y.push(v)), y.sort((s, l) => {
+    const d = l.split("/").length - s.split("/").length;
+    if (d !== 0)
+      return d;
+    const b = e.basename(s), u = e.basename(l);
+    return b === u ? 0 : b.endsWith("tsconfig.json") ? -1 : u.endsWith("tsconfig.json") ? 1 : b.endsWith("tsconfig.build.json") ? -1 : u.endsWith("tsconfig.build.json") ? 1 : b.localeCompare(u);
+  });
+  let m = await E("package.json");
+  m !== void 0 && (m = N(m));
+  const p = [], g = /* @__PURE__ */ new Set();
+  return await Promise.all(
+    y.map(async (s) => {
+      const l = e.relative(process.cwd(), s), d = i.readConfigFile(s, i.sys.readFile);
+      if (d.error !== void 0) {
+        h(
+          "error",
+          l,
+          i.formatDiagnosticsWithColorAndContext([d.error], {
+            getCanonicalFileName: W,
+            getCurrentDirectory: i.sys.getCurrentDirectory,
+            getNewLine: () => i.sys.newLine
+          })
+        );
+        return;
+      }
+      const b = e.basename(l), u = i.parseJsonConfigFileContent(
+        d.config,
+        i.sys,
+        e.dirname(s),
+        void 0,
+        b
+      ), T = 18003;
+      u.errors.filter((P) => P.code !== T).length > 0 && h(
+        "warn",
+        l,
+        i.formatDiagnosticsWithColorAndContext(u.errors, {
+          getCanonicalFileName: W,
+          getCurrentDirectory: i.sys.getCurrentDirectory,
+          getNewLine: () => i.sys.newLine
+        })
+      );
+      const F = s === v, A = l === b, k = u.fileNames.filter((P) => {
+        const D = P.slice(c);
+        return f.delete(D) ? (g.add(D), !0) : g.has(D) || D.endsWith(".json") || P.includes("node_modules") ? !1 : !F;
+      });
+      if (k.length === 0)
+        return;
+      y.length === 1 && (F || A) && f.clear();
+      const R = e.dirname(s);
+      let C = R, x = m;
+      do {
+        const P = e.join(C, "package.json");
+        if (w.includes(P)) {
+          x = P;
+          break;
+        }
+      } while (C !== t.globRoot && (C = e.dirname(C)));
+      const G = x === void 0 ? void 0 : { filePath: x, contents: await J(e.dirname(x)) }, O = {
+        typeScriptConfig: {
+          filePath: s,
+          compilerOptions: u.options
+        },
+        packageJson: G,
+        cwd: R,
+        filePaths: k
+      };
+      p.push(O);
+    })
+  ), f.size > 0 && p.push({
+    typeScriptConfig: void 0,
+    packageJson: m === void 0 ? void 0 : {
+      filePath: m,
+      contents: await J(e.dirname(m))
+    },
+    cwd: process.cwd(),
+    filePaths: Array.from(f).map((s) => e.join(process.cwd(), s))
+  }), p.sort((s, l) => s.cwd.localeCompare(l.cwd)), j.projectsData = p, p;
+}
+let M = !1;
+function te() {
+  M || (M = !0, process.exitCode !== void 0 && process.exitCode !== 0 ? h(
+    "warn",
+    j.codemodName,
+    "One or more exceptions occurred during the codemod run. Please review the output above."
+  ) : h(
+    "info",
+    j.codemodName,
+    `${B("green", "Codemod completed successfully.")} Recommended next steps:
+- Review the codemod changes.
+- If your project uses ESLint, run ESLint autofix on the changed files.
+- If your project uses Prettier, run Prettier on the changed files.
+- If your project uses TypeScript, run type checking to ensure there are no type errors.`
+  ));
+}
+async function oe(t, o) {
+  j.codemod = t, j.codemodName = o;
+  const n = await ee();
+  if (n.length === 0) {
+    h("error", o, `Failed to find any .js or .ts files in ${process.cwd()} to run the codemod on.`), process.exitCode = 1;
+    return;
+  }
+  await t.run(n), te();
+}
+const S = new $();
+S.name("@arcgis/codemod").description("Codemod for migrating or refactoring usages of ArcGIS Maps SDK for JavaScript");
+S.command("run").description("Run a single codemod").argument("<codemodName>", "Name of the transform").argument("[path]", "Directory to transform", process.cwd()).action(ne);
+async function ne(t, o) {
+  const n = K(o, { throwIfNoEntry: !1 });
+  if (n === void 0) {
+    h("error", "@arcgis/codemod", `Failed to find the target path: ${o}`), process.exitCode = 1;
+    return;
+  }
+  const r = n.isFile();
+  process.chdir(r ? e.dirname(o) : o);
+  let a;
+  try {
+    a = await q(/* @__PURE__ */ Object.assign({ "./codemods/arcgis-toolkit/codemod.ts": () => import("./codemod-mjvq6uf5.js"), "./codemods/refactor-out-esri-namespace/codemod.ts": () => import("./codemod-ZSjsrLkq.js") }), `./codemods/${t}/codemod.ts`, 4);
+  } catch (c) {
+    if (
+      // direct Node execution
+      typeof c == "object" && c !== null && "code" in c && c.code === "ERR_MODULE_NOT_FOUND" || // Vite build execution
+      String(c).includes("Unknown variable dynamic import:")
+    ) {
+      h("error", "@arcgis/codemod", `Can't find codemod by name "${t}".`), process.exitCode = 1;
+      return;
+    } else
+      throw c;
+  }
+  if (typeof a.codemod != "object" || a.codemod === null) {
+    h("error", "@arcgis/codemod", `Can't find codemod by name "${t}".`), process.exitCode = 1;
+    return;
+  }
+  await oe(a.codemod, t);
+}
+S.parse();
+export {
+  ge as d,
+  j as g,
+  te as p
+};

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import "./cli-DB4-Ai2J.js";
+import "@arcgis/toolkit/log";
+import "@commander-js/extra-typings";
+import "node:fs";
+import "@arcgis/components-build-utils";