@arcgis/codemod 5.2.0-next.12 → 5.2.0-next.120

package/LICENSE.md

@@ -1,12 +1,14 @@
 # Licensing
 
-COPYRIGHT © Esri
+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.
+This material is licensed for use under the Esri Master License Agreement (MLA), 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.
 
+See use restrictions at https://www.esri.com/content/dam/esrisites/en-us/media/legal/ma-full/ma-full.pdf.
+
 For additional information, contact:
 Environmental Systems Research Institute, Inc.
 Attn: Contracts and Legal Services Department

package/README.md

@@ -2,42 +2,52 @@
 
 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
+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.
 
-## Usage
+## Before you begin
 
-The codemod replaces `__esri` types with explicit imports from @arcgis/core.
+Ensure your project's dependencies are up to date, for example by running `pnpm install`.
 
-> Note: Before running the codemod, update all `@arcgis/*` packages in your `package.json` to the most recent version.
+If your project uses **ESLint, Prettier, or other formatters/linters**, run them after the codemod to ensure consistent formatting.
 
-Run it in the root of your project:
+> [!Note]
+> 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.
 
-```sh
-npx @arcgis/codemod run refactor-out-esri-namespace
-```
+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.
 
-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:
+## Available codemods
+
+- [`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
+
+The `refactor-out-esri-namespace` 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 or with an explicit target directory:
 
 ```sh
-npx @arcgis/codemod run refactor-out-esri-namespace target-directory
+npx @arcgis/codemod run refactor-out-esri-namespace [<target-directory>]
 ```
 
-### What codemod does
-
 **Before:**
 
 ```tsx
@@ -56,7 +66,7 @@ let geometry: Geometry;
 let featureSet: FeatureSet;
 ```
 
-### Warnings (Manual review required)
+#### Warnings (manual review required)
 
 The codemod will emit warnings for cases it cannot safely rewrite, including:
 
@@ -64,12 +74,88 @@ 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.
-If your project uses **ESLint, Prettier, or other formatters/linters**, run them after the codemod to ensure consistent formatting.
+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).
+
+Run it in the root of your project or with an explicit target directory:
+
+```sh
+npx @arcgis/codemod run normalize-calcite-icon-names [<target-directory>]
+```
+
+**Before:**
+
+```tsx
+<calcite-button iconStart="i3dGlasses" iconEnd="arrowLeft10" />
+```
+
+**After:**
+
+```tsx
+<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
+```
 
-> 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.
+[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.1/LICENSE.txt.
-For third party notices, see https://js.arcgis.com/5.1/third-party-notices.txt.
+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.
+For third-party notices, see https://js.arcgis.com/5.2/third-party-notices.txt.

package/dist/actions-LEFiI8Xk.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-DfAgo-jb.js";
+import { ModuleResolutionKind as K } from "typescript";
+import { a as w } from "./log-B76HBvov.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
+};