@arcgis/codemod 5.2.0-next.99 → 6.0.0-next.0

package/README.md

@@ -2,30 +2,39 @@
 
 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
-- Normalizes legacy Calcite icon names
-- Detects edge cases and warns when changes can’t be safely automated
-- Respects `.gitignore` by default
+This package provides automated refactors to help migrate away from deprecated or legacy patterns.
+These include codemods for removing the `__esri` namespace and
+converting global namespace types to explicit `@arcgis/core` imports,
+normalizing legacy Calcite icon names,
+and updating geometry operator usage.
 
 ## 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.
+- This codemod operates exclusively on TypeScript files. You do not need to run this tool if the project does not use TypeScript.
 
 ## Before you begin
 
+Ensure your project's dependencies are up to date, for example by running `pnpm install`.
+
 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.
+> Codemods modify files in place and do 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.
+
+By default, codemods run on all TypeScript files in the current directory and subdirectories.
+You can manually run it on a different directory by providing it as an argument.
+
+Codemods respect `.gitignore` files and will not modify any files ignored by them.
+
+## Available codemods
 
-## Usage
+- [`refactor-out-esri-namespace`](#refactor-out-the-__esri-namespace)
+- [`normalize-calcite-icon-names`](#normalize-calcite-icon-names)
+- [`geometry-operator-renames`](#rename-geometry-operators)
 
 ### Refactor out the `__esri` namespace
 
@@ -33,21 +42,12 @@ The `refactor-out-esri-namespace` codemod replaces `__esri` types with explicit
 
 > 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:
+Run it in the root of your project or with an explicit target directory:
 
 ```sh
-npx @arcgis/codemod run refactor-out-esri-namespace
+npx @arcgis/codemod run refactor-out-esri-namespace [<target-directory>]
 ```
 
-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 the codemod does
-
 **Before:**
 
 ```tsx
@@ -74,22 +74,20 @@ The codemod will emit warnings for cases it cannot safely rewrite, including:
 - Complex computed or dynamic type usage
 - Unresolvable symbols
 
-These will be reported in the console, manually review all changes before committing.
+These will be reported in the console. Manually review all changes before committing.
 
 ### Normalize Calcite icon names
 
-The `normalize-calcite-icon-names` codemod updates camelCase and legacy Calcite icon names to their normalized kebab-case equivalents. It handles icon attributes on Calcite components and traces icon values through variables, properties, assignments, function returns, and forwarded component properties. This helps prepare for [calcite-design-system#14967](https://github.com/Esri/calcite-design-system/issues/14967) and [calcite-design-system#14966](https://github.com/Esri/calcite-design-system/issues/14966).
+The `normalize-calcite-icon-names` codemod updates camelCase and legacy Calcite icon names to their normalized
+kebab-case equivalents. It handles icon attributes on Calcite components and traces icon values through variables,
+properties, assignments, function returns, and forwarded component properties. This helps prepare for
+[calcite-design-system#14967](https://github.com/Esri/calcite-design-system/issues/14967) and
+[calcite-design-system#14966](https://github.com/Esri/calcite-design-system/issues/14966).
 
-Run it in the root of your project:
+Run it in the root of your project or with an explicit target directory:
 
 ```sh
-npx @arcgis/codemod run normalize-calcite-icon-names
-```
-
-You can also provide a target directory:
-
-```sh
-npx @arcgis/codemod run normalize-calcite-icon-names target-directory
+npx @arcgis/codemod run normalize-calcite-icon-names [<target-directory>]
 ```
 
 **Before:**
@@ -104,6 +102,58 @@ npx @arcgis/codemod run normalize-calcite-icon-names target-directory
 <calcite-button iconStart="3d-glasses" iconEnd="arrow-left-10" />
 ```
 
+### Rename Geometry Operators
+
+In version 5.2, geometry operator exports and option types were renamed to improve consistency and discoverability.
+The `geometry-operator-renames` codemod updates geometry operator calls to use the new names.
+It additionally inlines namespace imports, which are no longer necessary.
+
+Run it in the root of your project or with an explicit target directory:
+
+```sh
+npx @arcgis/codemod run geometry-operator-renames [<target-directory>]
+```
+
+**Before:**
+
+```ts
+import * as bufferOperator from "@arcgis/core/geometry/operators/bufferOperator";
+const options: bufferOperator.Options = { unit: "meters" };
+const buffered = bufferOperator.execute(polyline, 250, options);
+```
+
+**After:**
+
+```ts
+import { bufferExecute, type BufferExecuteOptions } from "@arcgis/core/geometry/operators/bufferOperator";
+const options: BufferExecuteOptions = { unit: "meters" };
+const buffered = bufferExecute(polyline, 250, options);
+```
+
+## Versioning
+
+The codemods are available until the corresponding deprecated feature is removed.
+If migrating from a much older release, the codemod might no longer be available in the most recent version of the `@arcgis/codemod` package.
+In such cases, run the codemod from an older version, matching the version in the release notes:
+
+```sh
+npx @arcgis/codemod@5.2 run refactor-out-esri-namespace
+```
+
+## Troubleshooting
+
+Some codemods rely on type information to perform more accurate migrations.
+On large codebases, this may require more RAM than the default Node.js limit.
+If you encounter an out-of-memory error (like `Allocation failed - JavaScript heap out of memory`), re-run the codemod with a higher RAM limit:
+
+Example on Linux/macOS:
+
+```sh
+NODE_OPTIONS="--max-old-space-size=10240" npx @arcgis/codemod run normalize-calcite-icon-names
+```
+
+[Windows command line](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) and [PowerShell](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.6) use a different environment variable syntax.
+
 ## License
 
 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.2/LICENSE.txt.

package/dist/chunks/actions.js

@@ -0,0 +1,395 @@
+import { path as x } from "@arcgis/node-toolkit/path";
+import { SyntaxKind as I } from "ts-morph";
+import { g as D } from "./cli.js";
+import { ModuleResolutionKind as K } from "typescript";
+import { a as w } from "./log.js";
+import { capitalize as A } from "@arcgis/toolkit/string";
+import { log as P } from "@arcgis/toolkit/log";
+function j(t) {
+  const e = t.typeScriptConfig?.compilerOptions?.moduleResolution ?? K.Bundler;
+  return e >= K.Node16 && e <= K.NodeNext;
+}
+function V(t, e) {
+  const s = {};
+  q(t);
+  const { specifiers: i, names: m, lastImportIndex: r } = b(t), l = [], n = {}, c = [];
+  let p = j(D.project.projectData);
+  for (const [o, f] of Object.entries(e)) {
+    let a = i.get(o) ?? (o.startsWith(".") ? i.get(
+      x.relative(t.getDirectoryPath(), x.resolve(D.project.projectData.cwd, o))
+    ) : void 0);
+    if (a === void 0) {
+      const y = i.get(`${o}.js`);
+      y !== void 0 && (p = !0, a === void 0 ? a = y : a = [...a, ...y]);
+    }
+    for (const [y, g] of Object.entries(f)) {
+      const v = Array.isArray(g) ? g : [g];
+      for (const N of v)
+        N.do === "deprecate" ? R(y, o, s, a) : N.do === "add" ? C(o, y, N, a, l, n, m) : N.do === "rename" ? E(o, y, N, a, l, n, m) : N.do === "remove-namespace-import" && W(
+          o,
+          a,
+          l,
+          n,
+          c,
+          m
+        );
+    }
+  }
+  const d = Object.entries(n);
+  let u = r;
+  for (let o = 0; o < d.length; o += 1) {
+    const [f, a] = d[o], y = f.startsWith(".") ? M(
+      x.relative(t.getDirectoryPath(), x.resolve(D.project.projectData.cwd, f))
+    ) : f, g = p && y.startsWith("@arcgis/core") ? `${y}.js` : y, v = a.afterDeclaration === void 0 ? u : a.afterDeclaration.getChildIndex() + 1;
+    if (a.named.length > 0) {
+      let N = !0;
+      for (let h = 0; h < a.named.length; h += 1)
+        N &&= a.named[h].isTypeOnly;
+      t.insertImportDeclaration(v, {
+        isTypeOnly: N,
+        moduleSpecifier: g,
+        namedImports: a.named.map((h) => ({
+          name: h.name,
+          alias: h.alias,
+          isTypeOnly: h.isTypeOnly && !N
+        }))
+      }), u += 1;
+    }
+    a.default !== void 0 && (t.insertImportDeclaration(v, {
+      isTypeOnly: a.default.isTypeOnly,
+      moduleSpecifier: g,
+      defaultImport: a.default.name
+    }), u += 1), a["*"] !== void 0 && (t.insertImportDeclaration(v, {
+      isTypeOnly: a["*"].isTypeOnly,
+      moduleSpecifier: g,
+      namespaceImport: a["*"].name
+    }), u += 1);
+  }
+  if (Object.keys(s).length > 0) {
+    const o = Object.entries(s).map(([f, a]) => `${a.join(", ")} from ${f}`).join("; ");
+    P("warn", w(t), `Deprecated API usages found: ${o}`);
+  }
+  for (const o of c)
+    o.remove();
+  return l;
+}
+function q(t) {
+  const e = t.getChildSyntaxList()?.getFirstChild();
+  if (S === e)
+    return;
+  S = e, O.clear();
+  const s = /* @__PURE__ */ new Set();
+  i(t);
+  function i(m) {
+    for (const r of m.getStatements())
+      if (r.isKind(I.ImportDeclaration)) {
+        const l = r.getDefaultImport(), n = r.getNamespaceImport(), c = r.getNamedImports();
+        l && s.add(l.getText()), n && s.add(n.getText());
+        for (const p of c)
+          s.add(p.getAliasNode()?.getText() ?? p.getName());
+      } else r.isKind(I.ImportEqualsDeclaration) ? s.add(r.getName()) : r.isKind(I.ModuleDeclaration) ? i(r) : m.forEachDescendant((l) => {
+        if (!l.isKind(I.Identifier))
+          return;
+        const n = l.getParent();
+        if (n.isKind(I.QualifiedName) && n.getLeft() !== l || n.isKind(I.PropertyAccessExpression) && n.getExpression() !== l || (n.isKind(I.PropertyDeclaration) || n.isKind(I.PropertySignature) || n.isKind(I.PropertyAssignment)) && n.getNameNode() === l)
+          return;
+        const c = l.getText();
+        s.has(c) || O.add(l.getText());
+      });
+  }
+}
+function b(t) {
+  const e = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Set(), i = t.getStatements();
+  let m;
+  for (let l = 0; l < i.length; l += 1) {
+    const n = i[l];
+    if (!n.isKind(I.ImportDeclaration)) {
+      const a = n.getName?.();
+      a !== void 0 && s.add(a);
+      continue;
+    }
+    m = n;
+    const c = n.getModuleSpecifierValue(), p = e.get(c);
+    p === void 0 ? e.set(c, [n]) : p.push(n);
+    const d = n.getImportClause();
+    if (d === void 0)
+      continue;
+    const u = d.getDefaultImport()?.getText();
+    u !== void 0 && s.add(u);
+    const o = d.getNamedBindings();
+    if (o !== void 0)
+      if (o.isKind(I.NamedImports))
+        for (const f of o.getElements()) {
+          const a = f.getName();
+          s.add(a);
+        }
+      else {
+        const f = o.getName();
+        s.add(f);
+      }
+  }
+  const r = m === void 0 ? 0 : m.getChildIndex() + 1;
+  return { specifiers: e, names: s, lastImportIndex: r };
+}
+function R(t, e, s, i) {
+  if (i !== void 0) {
+    if (t === "default")
+      for (const m of i) {
+        const r = m.getDefaultImport();
+        if (r !== void 0) {
+          s[e] ??= [], s[e].push(r.getText());
+          return;
+        }
+      }
+    else if (t === "*")
+      for (const m of i) {
+        const r = m.getNamespaceImport();
+        if (r !== void 0) {
+          s[e] ??= [], s[e].push(r.getText());
+          return;
+        }
+      }
+    else
+      for (const m of i)
+        for (const r of m.getNamedImports())
+          if (r.getName() === t) {
+            s[e] ??= [], s[e].push(r.getName());
+            return;
+          }
+  }
+}
+function C(t, e, s, i, m, r, l) {
+  const n = e === "default";
+  if (n || e === "*") {
+    if (i !== void 0)
+      for (const p of i) {
+        const d = n ? p.getDefaultImport() : p.getNamespaceImport();
+        if (d !== void 0) {
+          s.isTypeOnly !== !0 && p.isTypeOnly() && p.setIsTypeOnly(!1), m.push({
+            specifier: t,
+            requestedName: e,
+            actualName: d.getText()
+          });
+          return;
+        }
+      }
+    const c = T(s.preferredAlias, void 0, t, l);
+    m.push({ specifier: t, requestedName: e, actualName: c }), r[t] ??= {
+      afterDeclaration: void 0,
+      named: [],
+      default: void 0,
+      "*": void 0
+    }, r[t].afterDeclaration ??= i?.[0], r[t][e] = {
+      name: c,
+      isTypeOnly: s.isTypeOnly === !0
+    };
+  } else {
+    let c, p;
+    if (i !== void 0) {
+      let o = !1;
+      for (const f of i)
+        if (f.getNamespaceImport() === void 0) {
+          p ??= f, c ??= f.isTypeOnly() && f.getDefaultImport() === void 0 ? f : void 0;
+          for (const a of f.getNamedImports())
+            if (a.getNameNode().getText() === e) {
+              if (o = !0, s.isTypeOnly !== !0) {
+                if (a.isTypeOnly())
+                  a.setIsTypeOnly(!1);
+                else if (f.isTypeOnly()) {
+                  for (const y of f.getNamedImports())
+                    y !== a && y.setIsTypeOnly(!0);
+                  f.setIsTypeOnly(!1);
+                }
+              }
+              m.push({
+                specifier: t,
+                requestedName: e,
+                actualName: a.getAliasNode()?.getText() ?? e
+              });
+              break;
+            }
+        }
+      if (o)
+        return;
+    }
+    const d = T(
+      s.preferAlias === !0 ? s.preferredAlias : e,
+      s.preferAlias === !0 ? e : s.preferredAlias,
+      t,
+      l
+    ), u = e === d ? void 0 : d;
+    if (s.isTypeOnly && c !== void 0)
+      c.addNamedImport({
+        name: e,
+        alias: u
+      });
+    else if (p !== void 0 && (!s.isTypeOnly || p.getDefaultImport() === void 0)) {
+      if (p.isTypeOnly() && !s.isTypeOnly) {
+        p.setIsTypeOnly(!1);
+        for (const o of p.getNamedImports())
+          o.setIsTypeOnly(!0);
+      }
+      p.addNamedImport({
+        name: e,
+        alias: u,
+        isTypeOnly: s.isTypeOnly && !p.isTypeOnly()
+      });
+    } else
+      r[t] ??= {
+        afterDeclaration: void 0,
+        named: [],
+        default: void 0,
+        "*": void 0
+      }, r[t].afterDeclaration ??= i?.[0], r[t].named.push({
+        name: e,
+        alias: u,
+        isTypeOnly: s.isTypeOnly === !0
+      });
+    m.push({ specifier: t, requestedName: e, actualName: d });
+  }
+}
+function E(t, e, s, i, m, r, l) {
+  if (i === void 0)
+    return;
+  const n = s.name ?? e, c = s.specifier ?? t, p = e === "default";
+  if (p || e === "*") {
+    for (const d of i) {
+      const u = p ? d.getDefaultImport() : d.getNamespaceImport();
+      if (u === void 0)
+        continue;
+      if (s.isTypeOnly === !1 && d.isTypeOnly()) {
+        d.setIsTypeOnly(!1);
+        for (const f of d.getNamedImports())
+          f.setIsTypeOnly(!0);
+      }
+      let o = n;
+      if (n !== e) {
+        const f = T(n, e, t, l);
+        n === f ? u.rename(n) : o = u.getText();
+      } else
+        o = u.getText();
+      t !== c && (d.getNamedImports().length === 0 ? d.setModuleSpecifier(c) : (p ? d.removeDefaultImport() : d.removeNamespaceImport(), r[c] ??= {
+        afterDeclaration: void 0,
+        named: [],
+        default: void 0,
+        "*": void 0
+      }, r[c].afterDeclaration ??= d, r[c][e] = {
+        name: o,
+        isTypeOnly: d.isTypeOnly()
+      })), m.push({
+        specifier: c,
+        requestedName: e,
+        actualName: o
+      });
+      break;
+    }
+    return;
+  }
+  for (const d of i) {
+    for (const o of d.getNamedImports()) {
+      if (o.getNameNode().getText() !== e)
+        continue;
+      if (s.isTypeOnly === !1) {
+        if (o.isTypeOnly())
+          o.setIsTypeOnly(!1);
+        else if (d.isTypeOnly()) {
+          d.setIsTypeOnly(!1);
+          for (const y of d.getNamedImports())
+            y !== o && y.setIsTypeOnly(!0);
+        }
+      }
+      let f = n;
+      const a = o.getAliasNode();
+      if (n !== e)
+        if (a === void 0) {
+          const y = T(n, e, t, l);
+          n === y ? o.getNameNode().asKind(I.Identifier)?.rename(n) : (o.setAlias(e), o.getNameNode().replaceWithText(n), f = e);
+        } else
+          o.getNameNode().replaceWithText(n), f = a.getText();
+      if (c !== t) {
+        const g = (j(D.project.projectData) || d.getModuleSpecifierValue().endsWith(".js")) && c.startsWith("@arcgis/core") ? `${c}.js` : c;
+        d.getNamedImports().length === 1 && d.getDefaultImport() === void 0 ? d.setModuleSpecifier(g) : (r[g] ??= { named: [] }, r[g].afterDeclaration ??= i?.[0], r[g].named.push({
+          name: n,
+          alias: n === f ? void 0 : f,
+          isTypeOnly: o.isTypeOnly()
+        }), o.remove());
+      }
+      m.push({
+        specifier: c,
+        requestedName: n,
+        actualName: a?.getText() ?? f
+      });
+      return;
+    }
+    const u = d.getNamespaceImport();
+    if (u)
+      for (const o of u.findReferencesAsNodes().slice(1)) {
+        const f = o.getParentIfKind(I.PropertyAccessExpression), a = o.getParentIfKind(I.QualifiedName)?.getParentIfKind(I.TypeReference), y = f ?? a;
+        if (!y)
+          continue;
+        const g = y.getText();
+        g.endsWith(e) && y.replaceWithText(g.replaceAll(e, n));
+      }
+  }
+}
+function W(t, e, s, i, m, r) {
+  if (e = e?.filter((u) => u.getNamespaceImport() != null), e === void 0 || e.length === 0)
+    return;
+  if (e.length !== 1)
+    throw Error(
+      `Multiple namespace imports of the same specifier (${JSON.stringify(t)}, #${e.length}) are not supported.`
+    );
+  const [l] = e, n = l.getNamespaceImport(), c = {}, p = /* @__PURE__ */ new Set();
+  for (const u of n.findReferencesAsNodes()) {
+    const o = u.getParentIfKind(I.PropertyAccessExpression), f = u.getParentIfKind(I.QualifiedName)?.getParentIfKind(I.TypeReference), a = o ?? f;
+    if (!a)
+      continue;
+    const y = a.getText().split(".").pop().trim();
+    c[y] ??= T(y, void 0, t, r);
+    const g = c[y];
+    a.replaceWithText(g), f || p.add(g);
+  }
+  i[t] ??= {
+    afterDeclaration: l,
+    named: []
+  };
+  const { named: d } = i[t];
+  for (const [u, o] of Object.entries(c))
+    d.push({
+      name: u,
+      alias: o === u ? void 0 : o,
+      isTypeOnly: !p.has(o)
+    }), s.push({
+      specifier: t,
+      requestedName: u,
+      actualName: o
+    });
+  m.push(l);
+}
+function T(t, e, s, i) {
+  if (t !== void 0) {
+    if (!i.has(t) && !O.has(t))
+      return i.add(t), t;
+    if (e !== void 0)
+      return T(e, void 0, s, i);
+  }
+  s.startsWith("@arcgis/core") && (s = `arcgisCore${s.slice(12)}`);
+  const m = s.split("/");
+  let r = t ?? "";
+  for (let l = m.length - 1; l >= 0; l--) {
+    const n = m[l].replaceAll($, "");
+    if (n !== r && (r = n + A(r), !i.has(r) && !O.has(r)))
+      return i.add(r), r;
+  }
+  for (let l = 2; ; l++) {
+    const n = r + l;
+    if (!i.has(n) && !O.has(n))
+      return i.add(n), n;
+  }
+}
+const $ = /[^a-zA-Z0-9$_]/gu, M = (t) => t.startsWith(".") ? t : `./${t}`, O = /* @__PURE__ */ new Set();
+let S;
+export {
+  V as p,
+  q as u
+};