@astryxdesign/cli 0.1.8-canary.0c4d8d7 → 0.1.8-canary.0db5dfd

package/{src/codemods → codemods}/transforms/v0.0.2/rename-topnav-title-to-heading.mjs

@@ -23,24 +23,30 @@ const TITLE_PROP_COMPONENTS = new Set([
   'XDSTopNavHeading',
 ]);
 
+/** @type {Record<string, string>} */
 const IMPORT_RENAMES = {
   XDSTopNavTitle: 'XDSTopNavHeading',
   XDSTopNavTitleProps: 'XDSTopNavHeadingProps',
 };
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
   let hasChanges = false;
 
   // 1. Rename `title` prop to `heading` on target components
-  root.find(j.JSXOpeningElement).forEach((path) => {
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
     const name = path.node.name;
     if (name.type !== 'JSXIdentifier' || !TITLE_PROP_COMPONENTS.has(name.name)) {
       return;
     }
 
-    path.node.attributes.forEach((attr) => {
+    path.node.attributes.forEach((/** @type {any} */ attr) => {
       if (attr.type === 'JSXAttribute' && attr.name.name === 'title') {
         attr.name.name = 'heading';
         hasChanges = true;
@@ -49,13 +55,13 @@ export default function transformer(file, api) {
   });
 
   // 2. Rename <XDSTopNavTitle> to <XDSTopNavHeading> (opening and closing tags)
-  root.find(j.JSXIdentifier, {name: 'XDSTopNavTitle'}).forEach((path) => {
+  root.find(j.JSXIdentifier, {name: 'XDSTopNavTitle'}).forEach((/** @type {any} */ path) => {
     path.node.name = 'XDSTopNavHeading';
     hasChanges = true;
   });
 
   // 3. Rename import specifiers: XDSTopNavTitle → XDSTopNavHeading, XDSTopNavTitleProps → XDSTopNavHeadingProps
-  root.find(j.ImportSpecifier).forEach((path) => {
+  root.find(j.ImportSpecifier).forEach((/** @type {any} */ path) => {
     const imported = path.node.imported;
     if (imported.type === 'Identifier' && imported.name in IMPORT_RENAMES) {
       const oldName = imported.name;

package/{src/codemods → codemods}/transforms/v0.0.2/unify-uncontrolled-to-defaultX.mjs

@@ -32,6 +32,11 @@ const RENAMES = [
   },
 ];
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
@@ -42,8 +47,8 @@ export default function transformer(file, api) {
       .find(j.JSXOpeningElement, {
         name: {name: component},
       })
-      .forEach((path) => {
-        path.node.attributes.forEach((attr) => {
+      .forEach((/** @type {any} */ path) => {
+        path.node.attributes.forEach((/** @type {any} */ attr) => {
           if (attr.type === 'JSXAttribute' && attr.name.name === oldProp) {
             attr.name.name = newProp;
             hasChanges = true;

package/{src/codemods → codemods}/transforms/v0.0.2/unify-visibility-to-onOpenChange.mjs

@@ -33,6 +33,11 @@ const SIMPLE_RENAMES = [
  */
 const MERGE_COMPONENTS = ['XDSHoverCard', 'XDSTooltip'];
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
@@ -44,8 +49,8 @@ export default function transformer(file, api) {
       .find(j.JSXOpeningElement, {
         name: {name: component},
       })
-      .forEach((path) => {
-        path.node.attributes.forEach((attr) => {
+      .forEach((/** @type {any} */ path) => {
+        path.node.attributes.forEach((/** @type {any} */ attr) => {
           if (attr.type === 'JSXAttribute' && attr.name.name === oldProp) {
             attr.name.name = 'onOpenChange';
             hasChanges = true;
@@ -60,13 +65,13 @@ export default function transformer(file, api) {
       .find(j.JSXOpeningElement, {
         name: {name: component},
       })
-      .forEach((path) => {
+      .forEach((/** @type {any} */ path) => {
         const attrs = path.node.attributes;
         const onShowAttr = attrs.find(
-          (a) => a.type === 'JSXAttribute' && a.name.name === 'onShow',
+          (/** @type {any} */ a) => a.type === 'JSXAttribute' && a.name.name === 'onShow',
         );
         const onHideAttr = attrs.find(
-          (a) => a.type === 'JSXAttribute' && a.name.name === 'onHide',
+          (/** @type {any} */ a) => a.type === 'JSXAttribute' && a.name.name === 'onHide',
         );
 
         if (onShowAttr && onHideAttr) {

package/{src/codemods → codemods}/transforms/v0.0.6/migrate-badge-children-to-label.mjs

@@ -19,6 +19,11 @@ export const meta = {
   pr: '#706',
 };
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
@@ -28,7 +33,7 @@ export default function transformer(file, api) {
     .find(j.JSXElement, {
       openingElement: {name: {name: 'XDSBadge'}},
     })
-    .forEach((path) => {
+    .forEach((/** @type {any} */ path) => {
       const {children} = path.node;
 
       // Skip if already self-closing or no children
@@ -36,7 +41,7 @@ export default function transformer(file, api) {
 
       // Filter out whitespace-only JSXText nodes
       const meaningful = children.filter(
-        (c) => !(c.type === 'JSXText' && !c.value.trim()),
+        (/** @type {any} */ c) => !(c.type === 'JSXText' && !c.value.trim()),
       );
 
       // Only transform single-child cases

package/{src/codemods → codemods}/transforms/v0.0.6/migrate-collapse-to-collapsible.mjs

@@ -36,6 +36,11 @@ const APPSHELL_DEPRECATED_PROPS = [
   'defaultIsSideNavCollapsed',
 ];
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
@@ -46,16 +51,17 @@ export default function transformer(file, api) {
     .find(j.JSXOpeningElement, {
       name: {name: 'XDSSideNav'},
     })
-    .forEach((path) => {
+    .forEach((/** @type {any} */ path) => {
       const attrs = path.node.attributes;
 
       // Find isCollapsible
       const isCollapsibleIdx = attrs.findIndex(
-        (a) => a.type === 'JSXAttribute' && a.name.name === 'isCollapsible',
+        (/** @type {any} */ a) => a.type === 'JSXAttribute' && a.name.name === 'isCollapsible',
       );
       if (isCollapsibleIdx === -1) return;
 
       // Collect all collapse-related props
+      /** @type {Record<string, any>} */
       const collapseProps = {};
       const indicesToRemove = [];
 
@@ -129,7 +135,7 @@ export default function transformer(file, api) {
     .find(j.JSXOpeningElement, {
       name: {name: 'XDSAppShell'},
     })
-    .forEach((path) => {
+    .forEach((/** @type {any} */ path) => {
       const attrs = path.node.attributes;
       for (let i = attrs.length - 1; i >= 0; i--) {
         const attr = attrs[i];

package/{src/codemods → codemods}/transforms/v0.0.6/migrate-radius-tokens.mjs

@@ -22,6 +22,7 @@ export const meta = {
     'Renames --radius-inner/content/element/container/page to --radius-0/1/2/3/4.',
 };
 
+/** @type {Record<string, string>} */
 const TOKEN_MAP = {
   '--radius-inner': '--radius-0',
   '--radius-content': '--radius-1',
@@ -38,17 +39,22 @@ const OLD_TOKENS_PATTERN = new RegExp(
   'g',
 );
 
-function replaceTokens(str) {
-  return str.replace(OLD_TOKENS_PATTERN, (match) => TOKEN_MAP[match] || match);
+function replaceTokens(/** @type {any} */ str) {
+  return str.replace(OLD_TOKENS_PATTERN, (/** @type {any} */ match) => TOKEN_MAP[match] || match);
 }
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
   let hasChanges = false;
 
   // Replace in string literals (StringLiteral or Literal with string value)
-  const replaceInStringNode = (path) => {
+  const replaceInStringNode = (/** @type {any} */ path) => {
     if (typeof path.node.value !== 'string') return;
     const original = path.node.value;
     const replaced = replaceTokens(original);
@@ -59,14 +65,14 @@ export default function transformer(file, api) {
   };
 
   root.find(j.StringLiteral).forEach(replaceInStringNode);
-  root.find(j.Literal).forEach((path) => {
+  root.find(j.Literal).forEach((/** @type {any} */ path) => {
     if (typeof path.node.value === 'string') {
       replaceInStringNode(path);
     }
   });
 
   // Replace in template literal quasis
-  root.find(j.TemplateLiteral).forEach((path) => {
+  root.find(j.TemplateLiteral).forEach((/** @type {any} */ path) => {
     for (const quasi of path.node.quasis) {
       const original = quasi.value.raw;
       const replaced = replaceTokens(original);

package/{src/codemods → codemods}/transforms/v0.0.6/migrate-shadow-tokens.mjs

@@ -34,6 +34,7 @@ export const meta = {
     'Renames --elevation-* to --shadow-base/menu/hover/dialog and --inset-shadow-border-*. Also migrates --shadow-1/2/3/4 from the brief numeric naming period.',
 };
 
+/** @type {Record<string, string>} */
 const TOKEN_MAP = {
   '--elevation-input-hover-success': '--inset-shadow-border-positive',
   '--elevation-input-hover-warning': '--inset-shadow-border-warning',
@@ -49,6 +50,7 @@ const TOKEN_MAP = {
   '--shadow-4': '--shadow-dialog',
 };
 
+/** @type {Record<string, string>} */
 const IDENTIFIER_MAP = {
   elevationDefaults: 'shadowDefaults',
   elevationVars: 'shadowVars',
@@ -64,16 +66,21 @@ const OLD_TOKENS_PATTERN = new RegExp(
   'g',
 );
 
-function replaceTokens(str) {
-  return str.replace(OLD_TOKENS_PATTERN, (match) => TOKEN_MAP[match] || match);
+function replaceTokens(/** @type {any} */ str) {
+  return str.replace(OLD_TOKENS_PATTERN, (/** @type {any} */ match) => TOKEN_MAP[match] || match);
 }
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
   let hasChanges = false;
 
-  const replaceInStringNode = (path) => {
+  const replaceInStringNode = (/** @type {any} */ path) => {
     if (typeof path.node.value !== 'string') return;
     const original = path.node.value;
     const replaced = replaceTokens(original);
@@ -84,11 +91,11 @@ export default function transformer(file, api) {
   };
 
   root.find(j.StringLiteral).forEach(replaceInStringNode);
-  root.find(j.Literal).forEach((path) => {
+  root.find(j.Literal).forEach((/** @type {any} */ path) => {
     if (typeof path.node.value === 'string') replaceInStringNode(path);
   });
 
-  root.find(j.TemplateLiteral).forEach((path) => {
+  root.find(j.TemplateLiteral).forEach((/** @type {any} */ path) => {
     for (const quasi of path.node.quasis) {
       const originalRaw = quasi.value.raw;
       const replacedRaw = replaceTokens(originalRaw);
@@ -100,7 +107,7 @@ export default function transformer(file, api) {
     }
   });
 
-  root.find(j.Identifier).forEach((path) => {
+  root.find(j.Identifier).forEach((/** @type {any} */ path) => {
     if (Object.hasOwn(IDENTIFIER_MAP, path.node.name)) {
       path.node.name = IDENTIFIER_MAP[path.node.name];
       hasChanges = true;

package/{src/codemods → codemods}/transforms/v0.0.6/migrate-skeleton-radius.mjs

@@ -16,6 +16,7 @@ export const meta = {
     'Replaces semantic radius prop values (inner, content, element, container) with numeric equivalents (0, 1, 2, 3).',
 };
 
+/** @type {Record<string, number>} */
 const RADIUS_MAP = {
   inner: 0,
   content: 1,
@@ -23,6 +24,11 @@ const RADIUS_MAP = {
   container: 3,
 };
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
@@ -32,7 +38,7 @@ export default function transformer(file, api) {
     .find(j.JSXOpeningElement, {
       name: {name: 'XDSSkeleton'},
     })
-    .forEach((path) => {
+    .forEach((/** @type {any} */ path) => {
       const attrs = path.node.attributes;
       for (const attr of attrs) {
         if (attr.type !== 'JSXAttribute') continue;

package/{src/codemods → codemods}/transforms/v0.0.6/migrate-token-names.mjs

@@ -66,6 +66,7 @@ export const meta = {
 
 // Ordered longest-first to prevent partial matches
 // (e.g. --color-educational-deemphasized must match before --color-educational)
+/** @type {Record<string, string>} */
 const TOKEN_MAP = {
   '--color-educational-deemphasized': '--color-info-muted',
   '--color-divider-high-contrast': '--color-border-strong',
@@ -114,17 +115,22 @@ const OLD_TOKENS_PATTERN = new RegExp(
   'g',
 );
 
-function replaceTokens(str) {
-  return str.replace(OLD_TOKENS_PATTERN, (match) => TOKEN_MAP[match] || match);
+function replaceTokens(/** @type {any} */ str) {
+  return str.replace(OLD_TOKENS_PATTERN, (/** @type {any} */ match) => TOKEN_MAP[match] || match);
 }
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
   let hasChanges = false;
 
   // Replace in string literals (StringLiteral or Literal with string value)
-  const replaceInStringNode = (path) => {
+  const replaceInStringNode = (/** @type {any} */ path) => {
     if (typeof path.node.value !== 'string') return;
     const original = path.node.value;
     const replaced = replaceTokens(original);
@@ -135,14 +141,14 @@ export default function transformer(file, api) {
   };
 
   root.find(j.StringLiteral).forEach(replaceInStringNode);
-  root.find(j.Literal).forEach((path) => {
+  root.find(j.Literal).forEach((/** @type {any} */ path) => {
     if (typeof path.node.value === 'string') {
       replaceInStringNode(path);
     }
   });
 
   // Replace in template literal quasis
-  root.find(j.TemplateLiteral).forEach((path) => {
+  root.find(j.TemplateLiteral).forEach((/** @type {any} */ path) => {
     for (const quasi of path.node.quasis) {
       const original = quasi.value.raw;
       const replaced = replaceTokens(original);

package/{src/codemods → codemods}/transforms/v0.0.7/rename-banner-variant-to-container.mjs

@@ -20,6 +20,11 @@ export const meta = {
   pr: '#814',
 };
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
@@ -30,8 +35,8 @@ export default function transformer(file, api) {
     .find(j.JSXOpeningElement, {
       name: {name: 'XDSBanner'},
     })
-    .forEach((path) => {
-      path.node.attributes.forEach((attr) => {
+    .forEach((/** @type {any} */ path) => {
+      path.node.attributes.forEach((/** @type {any} */ attr) => {
         if (attr.type === 'JSXAttribute' && attr.name.name === 'variant') {
           attr.name.name = 'container';
           hasChanges = true;
@@ -40,7 +45,7 @@ export default function transformer(file, api) {
     });
 
   // 2. Rename type references: XDSBannerVariant → XDSBannerContainer
-  root.find(j.Identifier, {name: 'XDSBannerVariant'}).forEach((path) => {
+  root.find(j.Identifier, {name: 'XDSBannerVariant'}).forEach((/** @type {any} */ path) => {
     path.node.name = 'XDSBannerContainer';
     hasChanges = true;
   });

package/{src/codemods → codemods}/transforms/v0.0.8/migrate-token-renames.mjs

@@ -50,6 +50,7 @@ export const meta = {
 // Token string renames (CSS custom property names)
 // =============================================================================
 
+/** @type {Record<string, string>} */
 const TOKEN_MAP = {
   // Color — Core Semantic
   '--color-secondary': '--color-neutral',
@@ -195,6 +196,7 @@ const TOKEN_MAP = {
 // JS identifier renames (import names, variable references)
 // =============================================================================
 
+/** @type {Record<string, string>} */
 const IDENTIFIER_MAP = {
   lineHeightVars: 'typeScaleVars',
   lineHeightDefaults: 'typeScaleDefaults',
@@ -213,21 +215,26 @@ const OLD_TOKENS_PATTERN = new RegExp(
   'g',
 );
 
-function replaceTokens(str) {
-  return str.replace(OLD_TOKENS_PATTERN, (match) => TOKEN_MAP[match] || match);
+function replaceTokens(/** @type {any} */ str) {
+  return str.replace(OLD_TOKENS_PATTERN, (/** @type {any} */ match) => TOKEN_MAP[match] || match);
 }
 
 // =============================================================================
 // Transformer
 // =============================================================================
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
   let hasChanges = false;
 
   // --- Pass 1: Rename token strings in string literals ---
-  const replaceInStringNode = (path) => {
+  const replaceInStringNode = (/** @type {any} */ path) => {
     if (typeof path.node.value !== 'string') return;
     const original = path.node.value;
     const replaced = replaceTokens(original);
@@ -238,14 +245,14 @@ export default function transformer(file, api) {
   };
 
   root.find(j.StringLiteral).forEach(replaceInStringNode);
-  root.find(j.Literal).forEach((path) => {
+  root.find(j.Literal).forEach((/** @type {any} */ path) => {
     if (typeof path.node.value === 'string') {
       replaceInStringNode(path);
     }
   });
 
   // --- Pass 2: Rename token strings in template literals ---
-  root.find(j.TemplateLiteral).forEach((path) => {
+  root.find(j.TemplateLiteral).forEach((/** @type {any} */ path) => {
     for (const quasi of path.node.quasis) {
       const original = quasi.value.raw;
       const replaced = replaceTokens(original);
@@ -263,7 +270,7 @@ export default function transformer(file, api) {
   // Special handling for imports: if the target name already exists as an import
   // specifier in the same declaration, remove the old specifier instead of renaming
   // it (avoids duplicate identifier declarations).
-  root.find(j.ImportSpecifier).forEach((importPath) => {
+  root.find(j.ImportSpecifier).forEach((/** @type {any} */ importPath) => {
     const oldName = importPath.node.imported.name;
     if (!Object.hasOwn(IDENTIFIER_MAP, oldName)) return;
 
@@ -271,7 +278,7 @@ export default function transformer(file, api) {
     const declaration = importPath.parent.node;
     const siblings = declaration.specifiers || [];
     const targetExists = siblings.some(
-      (s) =>
+      (/** @type {any} */ s) =>
         s !== importPath.node &&
         s.type === 'ImportSpecifier' &&
         s.imported.name === newName,
@@ -295,7 +302,7 @@ export default function transformer(file, api) {
   });
 
   // Rename remaining non-import identifier references
-  root.find(j.Identifier).forEach((path) => {
+  root.find(j.Identifier).forEach((/** @type {any} */ path) => {
     if (!Object.hasOwn(IDENTIFIER_MAP, path.node.name)) return;
     // Skip import specifiers (already handled above)
     if (path.parent.node.type === 'ImportSpecifier') return;

package/{src/codemods → codemods}/transforms/v0.0.8/rename-endslot-to-endcontent.mjs

@@ -23,13 +23,18 @@ export const meta = {
   pr: '#895',
 };
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
   let hasChanges = false;
 
   // 1. Rename JSX prop: <XDSButton endSlot={...} /> → <XDSButton endContent={...} />
-  root.find(j.JSXAttribute, {name: {name: 'endSlot'}}).forEach((path) => {
+  root.find(j.JSXAttribute, {name: {name: 'endSlot'}}).forEach((/** @type {any} */ path) => {
     path.node.name.name = 'endContent';
     hasChanges = true;
   });
@@ -37,7 +42,7 @@ export default function transformer(file, api) {
   // 2. Rename in all Identifier nodes named 'endSlot' that are object keys
   //    This covers both Property and ObjectProperty (parser-dependent),
   //    object literals, destructuring patterns, etc.
-  root.find(j.Identifier, {name: 'endSlot'}).forEach((path) => {
+  root.find(j.Identifier, {name: 'endSlot'}).forEach((/** @type {any} */ path) => {
     const parent = path.parent.node;
 
     // Object property key: { endSlot: value } or { endSlot } (shorthand)

package/{src/codemods → codemods}/transforms/v0.1.0/drop-xds-prefix-imports.mjs

@@ -68,7 +68,7 @@ const XDS_CORE_SOURCE = /^@xds\/core(\/.*)?$/;
  * Compute the bare (unprefixed) name for an XDS-prefixed identifier.
  * Returns null if the name is not XDS-prefixed in a renameable way.
  */
-function bareName(name) {
+function bareName(/** @type {any} */ name) {
   if (name.startsWith('useXDS') && name.length > 'useXDS'.length) {
     return 'use' + name.slice('useXDS'.length);
   }
@@ -91,7 +91,7 @@ function bareName(name) {
 const MOCK_METHOD_NAMES = new Set(['mock', 'doMock']);
 const MOCK_OBJECT_NAMES = new Set(['vi', 'jest']);
 
-function isMockCallee(callee) {
+function isMockCallee(/** @type {any} */ callee) {
   if (
     callee.type === 'MemberExpression' &&
     !callee.computed &&
@@ -105,7 +105,7 @@ function isMockCallee(callee) {
   return callee.type === 'Identifier' && callee.name === 'mock';
 }
 
-function isXdsCoreMockCall(node) {
+function isXdsCoreMockCall(/** @type {any} */ node) {
   if (node.type !== 'CallExpression' || !isMockCallee(node.callee))
     return false;
   const [arg] = node.arguments;
@@ -119,7 +119,7 @@ function isXdsCoreMockCall(node) {
 // Rename XDS-prefixed object-property KEYS (not values, not nested objects)
 // within the given AST subtree. Used only on a recognized @xds/core mock
 // factory, so the scope guard lives at the call site.
-function renameMockFactoryKeys(node, seen, onChange) {
+function renameMockFactoryKeys(/** @type {any} */ node, /** @type {any} */ seen, /** @type {any} */ onChange) {
   if (!node || typeof node !== 'object') return;
   if (Array.isArray(node)) {
     for (const child of node) renameMockFactoryKeys(child, seen, onChange);
@@ -158,6 +158,11 @@ function renameMockFactoryKeys(node, seen, onChange) {
   }
 }
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
@@ -176,12 +181,12 @@ export default function transformer(file, api) {
   // declaration. We gather: import locals, and top-level function/class/var
   // declaration names (the realistic collision sources for component wrappers).
   const existingBindings = new Set();
-  root.find(j.ImportDeclaration).forEach(path => {
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
     for (const spec of path.node.specifiers || []) {
       if (spec.local && spec.local.name) existingBindings.add(spec.local.name);
     }
   });
-  const collectDeclName = node => {
+  const collectDeclName = (/** @type {any} */ node) => {
     if (!node) return;
     if (
       (node.type === 'FunctionDeclaration' ||
@@ -195,7 +200,7 @@ export default function transformer(file, api) {
       }
     }
   };
-  root.find(j.Program).forEach(path => {
+  root.find(j.Program).forEach((/** @type {any} */ path) => {
     for (const stmt of path.node.body) {
       collectDeclName(stmt);
       // Unwrap `export function X` / `export const X`.
@@ -209,11 +214,11 @@ export default function transformer(file, api) {
   });
 
   // 1. Rewrite import specifiers from @xds/core
-  root.find(j.ImportDeclaration).forEach(path => {
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
     const source = path.node.source.value;
     if (typeof source !== 'string' || !XDS_CORE_SOURCE.test(source)) return;
 
-    path.node.specifiers = (path.node.specifiers || []).map(spec => {
+    path.node.specifiers = (path.node.specifiers || []).map((/** @type {any} */ spec) => {
       if (spec.type !== 'ImportSpecifier') return spec; // default/namespace
       const importedName = spec.imported.name;
       const bare = bareName(importedName);
@@ -253,7 +258,7 @@ export default function transformer(file, api) {
   });
 
   // 2. Rewrite re-exports from @xds/core
-  root.find(j.ExportNamedDeclaration).forEach(path => {
+  root.find(j.ExportNamedDeclaration).forEach((/** @type {any} */ path) => {
     if (!path.node.source) return;
     const source = path.node.source.value;
     if (typeof source !== 'string' || !XDS_CORE_SOURCE.test(source)) return;
@@ -279,7 +284,7 @@ export default function transformer(file, api) {
   // not a reference to an imported binding, so it must match the renamed export
   // name of the mocked module regardless of what the file imports.
   const seenMockNodes = new Set();
-  root.find(j.CallExpression).forEach(path => {
+  root.find(j.CallExpression).forEach((/** @type {any} */ path) => {
     if (!isXdsCoreMockCall(path.node)) return;
     // Only walk the factory argument(s), never the module-path string.
     for (const arg of path.node.arguments.slice(1)) {
@@ -295,7 +300,7 @@ export default function transformer(file, api) {
 
   // 4. Rename references to renamed local bindings
   // Identifiers (type refs, value refs, etc.)
-  root.find(j.Identifier).forEach(path => {
+  root.find(j.Identifier).forEach((/** @type {any} */ path) => {
     const newName = localRenames.get(path.node.name);
     if (!newName) return;
     // Skip object property keys like `{ XDSButton: ... }` (not a reference to
@@ -322,7 +327,7 @@ export default function transformer(file, api) {
   });
 
   // JSX element names: <XDSButton> -> <Button>
-  root.find(j.JSXIdentifier).forEach(path => {
+  root.find(j.JSXIdentifier).forEach((/** @type {any} */ path) => {
     const newName = localRenames.get(path.node.name);
     if (newName) {
       path.node.name = newName;
@@ -344,7 +349,7 @@ export default function transformer(file, api) {
   // renamed binding. Renaming already-bare names is a no-op, so re-visiting a
   // node the earlier passes handled is harmless.
   const seenTypeNodes = new Set();
-  const renameTypeReferences = node => {
+  const renameTypeReferences = (/** @type {any} */ node) => {
     if (!node || typeof node !== 'object') return;
     if (Array.isArray(node)) {
       for (const child of node) renameTypeReferences(child);