@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/{src/codemods → codemods}/integration-discovery.test.mjs

@@ -54,7 +54,7 @@ function scaffold(codemodFiles) {
 // from the vitest cwd (the repo root) instead.
 const codemodModulePath = path.resolve(
   process.cwd(),
-  'packages/cli/src/codemod.mjs',
+  'packages/cli/authoring/codemod.mjs',
 );
 const codemodModuleUrl = pathToFileURL(codemodModulePath).href;
 

package/{src/codemods → codemods}/integration-runner.mjs

@@ -31,15 +31,15 @@ import {
  * Optional codemods (isOptional) are skipped unless explicitly requested via
  * `codemod` (matched against the codemod id).
  *
- * @param {Array<{version: string, codemods: Array<object>}>} versionGroups
+ * @param {Array<{version: string, codemods: Array<import('../types/codemod').CodemodEntry>}>} versionGroups
  * @param {object} options
  * @param {boolean} options.apply
  * @param {string} options.path source directory to scan
  * @param {string} [options.codemod] run only this codemod id
  * @param {Set<string>} [options.skipCodemods] codemod ids to exclude
- * @param {Function} options.jscodeshift
+ * @param {import('../types/codemod').JscodeshiftFactory} options.jscodeshift
  * @param {boolean} [options.silent]
- * @returns {{totalFilesChanged: number, totalTransformsApplied: number, writtenFiles: string[], errors: Array, skippedOptional: Array}}
+ * @returns {{totalFilesChanged: number, totalTransformsApplied: number, writtenFiles: string[], errors: Array<{file: string, codemod: string, error: string}>, skippedOptional: Array<import('../types/codemod').CodemodEntry>}}
  */
 export function runIntegrationCodemods(
   versionGroups,
@@ -49,12 +49,17 @@ export function runIntegrationCodemods(
 
   let totalFilesChanged = 0;
   let totalTransformsApplied = 0;
+  /** @type {string[]} */
   const writtenFiles = [];
+  /** @type {Array<{file: string, codemod: string, error: string}>} */
   const errors = [];
+  /** @type {Array<import('../types/codemod').CodemodEntry>} */
   const skippedOptional = [];
 
   // Flatten and split by type, preserving version ordering.
+  /** @type {Array<import('../types/codemod').CodemodEntry>} */
   const configEntries = [];
+  /** @type {Array<import('../types/codemod').CodemodEntry>} */
   const codeEntries = [];
   for (const {version, codemods} of versionGroups) {
     for (const entry of codemods) {

package/{src/codemods → codemods}/registry.mjs

@@ -22,6 +22,7 @@ const registry = new Map([
   ['0.1.3', () => import('./transforms/v0.1.3/index.mjs')],
   ['0.1.5', () => import('./transforms/v0.1.5/index.mjs')],
   ['0.1.7', () => import('./transforms/v0.1.7/index.mjs')],
+  ['0.1.8', () => import('./transforms/v0.1.8/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers
@@ -44,16 +45,18 @@ export const latestVersion = versions[versions.length - 1];
  *
  * @param {string} from - Current version (exclusive)
  * @param {string} to - Target version (inclusive)
- * @returns {Promise<Array<{version: string, transforms: Array<{name: string, module: Function}>}>>}
+ * @returns {Promise<Array<{version: string, transforms: Array<{name: string, transform: import('../types/codemod').CodemodTransform, meta: {title: string, description?: string}}>}>>}
  */
 export async function getTransformsBetween(from, to) {
   const applicable = versions.filter(
     v => semverCompare(v, from) > 0 && semverCompare(v, to) <= 0,
   );
+  /** @type {Array<{version: string, transforms: Array<{name: string, transform: import('../types/codemod').CodemodTransform, meta: {title: string, description?: string}}>}>} */
   const results = [];
 
   for (const version of applicable) {
     const loader = registry.get(version);
+    if (!loader) continue;
     const manifest = await loader();
     results.push({
       version,

package/{src/codemods → codemods}/run-codemod.mjs

@@ -29,7 +29,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as p from '@clack/prompts';
+import * as p from '../lib/term-log.mjs';
 import {findConfigPath} from '../lib/project.mjs';
 import {fixDirectiveCorruption, validateOutput} from './runner.mjs';
 
@@ -49,7 +49,9 @@ const PARSEABLE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
  * @returns {string[]}
  */
 export function findSourceFiles(dir) {
+  /** @type {string[]} */
   const results = [];
+  /** @param {string} currentDir */
   function walk(currentDir) {
     let entries;
     try {
@@ -74,6 +76,7 @@ export function findSourceFiles(dir) {
 /**
  * No-op log surface for silent (`--json`) mode.
  * @param {boolean} silent
+ * @returns {import('../types/codemod').CliLog}
  */
 export function makeLog(silent) {
   return silent
@@ -84,9 +87,9 @@ export function makeLog(silent) {
 /**
  * Apply a config codemod to the consumer's astryx.config.* file.
  *
- * @param {object} entry normalized codemod entry {id, codemod, package}
- * @param {{apply: boolean, log: object, jscodeshift: Function}} ctx
- * @returns {{filesChanged: number, writtenFiles: string[], errors: Array}}
+ * @param {import('../types/codemod').CodemodEntry} entry normalized codemod entry {id, codemod, package}
+ * @param {{apply: boolean, log: import('../types/codemod').CliLog, jscodeshift: import('../types/codemod').JscodeshiftFactory}} ctx
+ * @returns {import('../types/codemod').CodemodRunResult}
  */
 export function runConfigCodemod(entry, {apply, log, jscodeshift}) {
   const {codemod, id, package: pkg} = entry;
@@ -135,11 +138,12 @@ export function runConfigCodemod(entry, {apply, log, jscodeshift}) {
       errors: [],
     };
   } catch (err) {
-    log.error(`    ✗ ${relativePath} — ${err.message}`);
+    const message = /** @type {any} */ (err).message;
+    log.error(`    ✗ ${relativePath} — ${message}`);
     return {
       filesChanged: 0,
       writtenFiles: [],
-      errors: [{file: relativePath, codemod: name, error: err.message}],
+      errors: [{file: relativePath, codemod: name, error: message}],
     };
   }
 }
@@ -147,10 +151,10 @@ export function runConfigCodemod(entry, {apply, log, jscodeshift}) {
 /**
  * Apply a code codemod to discovered source files.
  *
- * @param {object} entry normalized codemod entry {id, codemod, package}
+ * @param {import('../types/codemod').CodemodEntry} entry normalized codemod entry {id, codemod, package}
  * @param {string[]} files
- * @param {{apply: boolean, log: object, jscodeshift: Function}} ctx
- * @returns {{filesChanged: number, writtenFiles: string[], errors: Array}}
+ * @param {{apply: boolean, log: import('../types/codemod').CliLog, jscodeshift: import('../types/codemod').JscodeshiftFactory}} ctx
+ * @returns {import('../types/codemod').CodemodRunResult}
  */
 export function runCodeCodemod(entry, files, {apply, log, jscodeshift}) {
   const {codemod, id, package: pkg} = entry;
@@ -158,7 +162,9 @@ export function runCodeCodemod(entry, files, {apply, log, jscodeshift}) {
   const extensions = new Set(codemod.fileExtensions ?? DEFAULT_CODE_EXTENSIONS);
 
   let filesChanged = 0;
+  /** @type {string[]} */
   const writtenFiles = [];
+  /** @type {Array<{file: string, codemod: string, error: string}>} */
   const errors = [];
 
   for (const filePath of files) {
@@ -198,8 +204,9 @@ export function runCodeCodemod(entry, files, {apply, log, jscodeshift}) {
         log.warn(`    ~ ${relativePath} (would change)`);
       }
     } catch (err) {
-      log.error(`    ✗ ${relativePath} — ${err.message}`);
-      errors.push({file: relativePath, codemod: name, error: err.message});
+      const message = /** @type {any} */ (err).message;
+      log.error(`    ✗ ${relativePath} — ${message}`);
+      errors.push({file: relativePath, codemod: name, error: message});
     }
   }
 

package/{src/codemods → codemods}/runner.mjs

@@ -10,7 +10,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as p from '@clack/prompts';
+import * as p from '../lib/term-log.mjs';
 import {humanLog} from '../lib/json.mjs';
 import {runConfigCodemod} from './run-codemod.mjs';
 
@@ -51,6 +51,7 @@ export function fixDirectiveCorruption(code) {
  * @returns {string[]}
  */
 function findSourceFiles(dir) {
+  /** @type {string[]} */
   const results = [];
   const extensions = new Set([
     '.tsx',
@@ -65,6 +66,7 @@ function findSourceFiles(dir) {
     '.less',
   ]);
 
+  /** @param {string} currentDir */
   function walk(currentDir) {
     let entries;
     try {
@@ -96,8 +98,9 @@ function findSourceFiles(dir) {
  *
  * @param {string} result - The transformed source code
  * @param {string} source - The original source code
- * @param {Function} j - jscodeshift instance (with parser configured)
- * @returns {{ valid: boolean, reason?: string }}
+ * @param {import('../types/codemod').JscodeshiftFactory} j - jscodeshift instance (with parser configured)
+ * @param {{parse?: boolean}} [options]
+ * @returns {{ valid: true } | { valid: false, reason: string }}
  */
 export function validateOutput(result, source, j, {parse = true} = {}) {
   // Check 1: Re-parse the output — catches syntax-breaking corruption
@@ -105,9 +108,10 @@ export function validateOutput(result, source, j, {parse = true} = {}) {
     try {
       j(result);
     } catch (parseError) {
+      const message = /** @type {any} */ (parseError).message;
       return {
         valid: false,
-        reason: `transform produced unparseable output: ${parseError.message}`,
+        reason: `transform produced unparseable output: ${message}`,
       };
     }
   }
@@ -147,9 +151,9 @@ export function validateOutput(result, source, j, {parse = true} = {}) {
  * with the same `(file, api) => string | null | undefined` contract used by
  * `createConfigCodemod`.
  *
- * @param {{name: string, transform: Function, meta: object, optional?: boolean}} transformEntry
+ * @param {{name: string, transform: import('../types/codemod').CodemodTransform, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, optional?: boolean}} transformEntry
  * @param {string} version
- * @returns {{id: string, type: 'code'|'config', codemod: object, package: string, version: string}}
+ * @returns {import('../types/codemod').CodemodEntry}
  */
 function toUnifiedEntry(transformEntry, version) {
   const {name, transform, meta, optional} = transformEntry;
@@ -171,20 +175,20 @@ function toUnifiedEntry(transformEntry, version) {
 /**
  * Run codemods against source files.
  *
- * @param {Array<{version: string, transforms: Array}>} versionManifests
+ * @param {Array<{version: string, transforms: Array<{name: string, transform: import('../types/codemod').CodemodTransform, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, optional?: boolean}>}>} versionManifests
  * @param {object} options
  * @param {boolean} options.apply - Write changes to disk
  * @param {string} options.path - Source directory to scan
  * @param {string|undefined} options.codemod - Run only this specific transform
  * @param {Set<string>} [options.skipCodemods] - Transform names to exclude
  * @param {boolean} [options.silent] - Suppress all human-facing output (for --json)
- * @returns {{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, writtenFiles: string[], errors: Array, skippedOptional: Array}}
+ * @returns {Promise<{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, writtenFiles: string[], errors: Array<{file: string, codemod: string, error: string}>, skippedOptional: Array<{name: string, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, version: string}>} | {ok: false, reason: string, resolvedPath: string}>}
  */
 export async function runCodemods(
   versionManifests,
   {apply, path: srcPath, codemod, skipCodemods, silent = false},
 ) {
-  // No-op stub object so silent mode skips clack stdout entirely without
+  // No-op stub object so silent mode skips log output entirely without
   // littering the body with `if (!silent)` guards.
   const log = silent
     ? {step() {}, info() {}, success() {}, warn() {}, error() {}, message() {}}
@@ -208,11 +212,11 @@ export async function runCodemods(
     return {ok: false, reason: 'source_path_missing', resolvedPath};
   }
 
+  /** @type {string[]} */
   let files = [];
   if (sourcePathExists) {
     log.step(`Scanning ${resolvedPath} for source files...`);
     files = findSourceFiles(resolvedPath);
-
     if (files.length === 0) {
       log.warn('No source files found.');
     } else {
@@ -223,15 +227,20 @@ export async function runCodemods(
   }
 
   // Dynamically import jscodeshift
-  const jscodeshift = (await import('jscodeshift')).default;
+  const jscodeshift =
+    /** @type {import('../types/codemod').JscodeshiftFactory} */ (
+      (await import('jscodeshift')).default
+    );
 
   let totalFilesChanged = 0;
   let totalTransformsApplied = 0;
   let totalValidationBlocked = 0;
+  /** @type {Array<{file: string, codemod: string, error: string}>} */
   const errors = [];
+  /** @type {string[]} */
   const writtenFiles = [];
+  /** @type {Array<{name: string, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, version: string}>} */
   const skippedOptional = [];
-
   for (const {version, transforms} of versionManifests) {
     log.step(`Applying v${version} codemods...`);
 
@@ -333,8 +342,9 @@ export async function runCodemods(
             }
           }
         } catch (err) {
-          log.error(`    ✗ ${relativePath} — ${err.message}`);
-          errors.push({file: relativePath, codemod: name, error: err.message});
+          const message = /** @type {any} */ (err).message;
+          log.error(`    ✗ ${relativePath} — ${message}`);
+          errors.push({file: relativePath, codemod: name, error: message});
         }
       }
 

package/{src/codemods → codemods}/transforms/v0.0.10/remove-size-props.mjs

@@ -32,6 +32,11 @@ export const meta = {
   pr: '#966',
 };
 
+/**
+ * @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);
@@ -40,7 +45,7 @@ export default function transformer(file, api) {
   // 1. Remove size JSX prop from target components
   root
     .find(j.JSXOpeningElement)
-    .filter((path) => {
+    .filter((/** @type {any} */ path) => {
       const name = path.node.name;
       // Handle simple names like <XDSStatusDot>
       if (name.type === 'JSXIdentifier') {
@@ -48,10 +53,10 @@ export default function transformer(file, api) {
       }
       return false;
     })
-    .forEach((path) => {
+    .forEach((/** @type {any} */ path) => {
       const attrs = path.node.attributes;
       const sizeIdx = attrs.findIndex(
-        (attr) =>
+        (/** @type {any} */ attr) =>
           attr.type === 'JSXAttribute' &&
           attr.name &&
           attr.name.name === 'size',
@@ -63,7 +68,7 @@ export default function transformer(file, api) {
     });
 
   // 2. Remove size type imports (XDSStatusDotSize, XDSProgressBarSize)
-  root.find(j.ImportDeclaration).forEach((path) => {
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
     const specifiers = path.node.specifiers;
     if (!specifiers) return;
 

package/{src/codemods → codemods}/transforms/v0.0.12/add-is-icon-only.mjs

@@ -50,6 +50,11 @@ export const meta = {
   pr: '#1321',
 };
 
+/**
+ * @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);
@@ -61,7 +66,7 @@ export default function transformer(file, api) {
   // Uses direct body manipulation instead of jscodeshift's insertAfter(),
   // which has a known bug that corrupts 'use client' directives into
   // double semicolons ('use client';;).
-  function insertAfterInBody(targetPath, newNode) {
+  function insertAfterInBody(/** @type {any} */ targetPath, /** @type {any} */ newNode) {
     const body = root.get().node.program.body;
     const targetIndex = body.indexOf(targetPath.node);
     if (targetIndex !== -1) {
@@ -69,14 +74,14 @@ export default function transformer(file, api) {
     } else {
       // Fallback: insert after all imports
       const lastImportIdx = body.findLastIndex(
-        (n) => n.type === 'ImportDeclaration',
+        (/** @type {any} */ n) => n.type === 'ImportDeclaration',
       );
       body.splice(lastImportIdx + 1, 0, newNode);
     }
   }
 
   // ---- 1. JSX elements: convert icon-only XDSButton to XDSIconButton ----
-  root.find(j.JSXOpeningElement).forEach((path) => {
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
     const name = path.node.name;
     const componentName =
       name.type === 'JSXIdentifier' ? name.name : null;
@@ -85,13 +90,13 @@ export default function transformer(file, api) {
     const attrs = path.node.attributes;
 
     const hasIcon = attrs.some(
-      (a) => a.type === 'JSXAttribute' && a.name?.name === 'icon',
+      (/** @type {any} */ a) => a.type === 'JSXAttribute' && a.name?.name === 'icon',
     );
     const hasChildren = attrs.some(
-      (a) => a.type === 'JSXAttribute' && a.name?.name === 'children',
+      (/** @type {any} */ a) => a.type === 'JSXAttribute' && a.name?.name === 'children',
     );
     const hasIsIconOnly = attrs.some(
-      (a) => a.type === 'JSXAttribute' && a.name?.name === 'isIconOnly',
+      (/** @type {any} */ a) => a.type === 'JSXAttribute' && a.name?.name === 'isIconOnly',
     );
 
     if (!hasIcon || hasChildren || hasIsIconOnly) return;
@@ -101,7 +106,7 @@ export default function transformer(file, api) {
     const hasJSXChildren =
       parent.type === 'JSXElement' &&
       parent.children &&
-      parent.children.some((child) => {
+      parent.children.some((/** @type {any} */ child) => {
         if (child.type === 'JSXText') return child.value.trim() !== '';
         return true;
       });
@@ -128,7 +133,7 @@ export default function transformer(file, api) {
   });
 
   // ---- 2. Remove redundant children that match label ----
-  root.find(j.JSXElement).forEach((path) => {
+  root.find(j.JSXElement).forEach((/** @type {any} */ path) => {
     const opening = path.node.openingElement;
     const name = opening.name;
     const componentName =
@@ -137,13 +142,13 @@ export default function transformer(file, api) {
 
     const attrs = opening.attributes;
     const hasIcon = attrs.some(
-      (a) => a.type === 'JSXAttribute' && a.name?.name === 'icon',
+      (/** @type {any} */ a) => a.type === 'JSXAttribute' && a.name?.name === 'icon',
     );
     if (!hasIcon) return;
 
     // Get label value
     const labelAttr = attrs.find(
-      (a) => a.type === 'JSXAttribute' && a.name?.name === 'label',
+      (/** @type {any} */ a) => a.type === 'JSXAttribute' && a.name?.name === 'label',
     );
     if (!labelAttr || !labelAttr.value) return;
 
@@ -177,7 +182,7 @@ export default function transformer(file, api) {
   });
 
   // ---- 3. Object literals: add isIconOnly to button config objects ----
-  root.find(j.JSXOpeningElement).forEach((path) => {
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
     const name = path.node.name;
     const componentName =
       name.type === 'JSXIdentifier' ? name.name : null;
@@ -185,7 +190,7 @@ export default function transformer(file, api) {
 
     const attrs = path.node.attributes;
     const buttonAttr = attrs.find(
-      (a) =>
+      (/** @type {any} */ a) =>
         a.type === 'JSXAttribute' &&
         a.name?.name === 'button' &&
         a.value?.type === 'JSXExpressionContainer' &&
@@ -197,13 +202,13 @@ export default function transformer(file, api) {
     const props = obj.properties;
 
     const hasIcon = props.some(
-      (p) => (p.type === 'Property' || p.type === 'ObjectProperty') && p.key?.name === 'icon',
+      (/** @type {any} */ p) => (p.type === 'Property' || p.type === 'ObjectProperty') && p.key?.name === 'icon',
     );
     const hasChildren = props.some(
-      (p) => (p.type === 'Property' || p.type === 'ObjectProperty') && p.key?.name === 'children',
+      (/** @type {any} */ p) => (p.type === 'Property' || p.type === 'ObjectProperty') && p.key?.name === 'children',
     );
     const hasIsIconOnly = props.some(
-      (p) => (p.type === 'Property' || p.type === 'ObjectProperty') && p.key?.name === 'isIconOnly',
+      (/** @type {any} */ p) => (p.type === 'Property' || p.type === 'ObjectProperty') && p.key?.name === 'isIconOnly',
     );
 
     if (hasIcon && !hasChildren && !hasIsIconOnly) {
@@ -222,7 +227,7 @@ export default function transformer(file, api) {
     hasRemainingXDSButton = true;
   });
   // Also check for XDSButton in type annotations (e.g. typeof XDSButton)
-  root.find(j.Identifier, {name: 'XDSButton'}).forEach((path) => {
+  root.find(j.Identifier, {name: 'XDSButton'}).forEach((/** @type {any} */ path) => {
     // Skip JSX identifiers (already counted above) and import specifiers
     if (path.parent.node.type === 'JSXOpeningElement' ||
         path.parent.node.type === 'JSXClosingElement' ||
@@ -232,9 +237,9 @@ export default function transformer(file, api) {
 
   if (needsIconButtonImport) {
     let alreadyImported = false;
-    root.find(j.ImportDeclaration).forEach((path) => {
+    root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
       if (path.node.specifiers.some(
-        (s) => s.type === 'ImportSpecifier' && s.imported.name === 'XDSIconButton',
+        (/** @type {any} */ s) => s.type === 'ImportSpecifier' && s.imported.name === 'XDSIconButton',
       )) {
         alreadyImported = true;
       }
@@ -244,13 +249,13 @@ export default function transformer(file, api) {
       // Handle @xds/core/Button import — may need splitting if it has
       // other specifiers (type imports, other components)
       if (!hasRemainingXDSButton) {
-        root.find(j.ImportDeclaration).forEach((path) => {
+        root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
           if (alreadyImported) return;
           const source = path.node.source.value;
           if (source !== '@xds/core/Button') return;
           const specs = path.node.specifiers;
           const btnIdx = specs.findIndex(
-            (s) => s.type === 'ImportSpecifier' && s.imported.name === 'XDSButton',
+            (/** @type {any} */ s) => s.type === 'ImportSpecifier' && s.imported.name === 'XDSButton',
           );
           if (btnIdx === -1) return;
 
@@ -276,7 +281,7 @@ export default function transformer(file, api) {
 
       // For barrel imports, add the specifier
       if (!alreadyImported) {
-        root.find(j.ImportDeclaration).forEach((path) => {
+        root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
           if (alreadyImported) return;
           if (path.node.source.value === '@xds/core') {
             path.node.specifiers.push(
@@ -296,7 +301,7 @@ export default function transformer(file, api) {
 
         const xdsImports = root
           .find(j.ImportDeclaration)
-          .filter((p) => p.node.source.value.startsWith('@xds/'));
+          .filter((/** @type {any} */ p) => p.node.source.value.startsWith('@xds/'));
 
         if (xdsImports.length > 0) {
           insertAfterInBody(xdsImports.at(-1), newImport);

package/{src/codemods → codemods}/transforms/v0.0.13/icon-name-deprecations.mjs

@@ -23,6 +23,7 @@ export const meta = {
   pr: '#1503',
 };
 
+/** @type {Record<string, string>} */
 const RENAMES = {
   checkCircle: 'success',
   xCircle: 'error',
@@ -31,13 +32,18 @@ const RENAMES = {
 /** Prop names that accept XDSIconName values */
 const ICON_PROPS = new Set(['icon', 'name', 'selectedIcon']);
 
+/**
+ * @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;
 
   // Helper: rename a string literal node if it matches a deprecated name
-  function renameStringLiteral(node) {
+  function renameStringLiteral(/** @type {any} */ node) {
     if (!node) return false;
     if (node.type === 'StringLiteral' || node.type === 'Literal') {
       const newName = RENAMES[node.value];
@@ -51,7 +57,8 @@ export default function transformer(file, api) {
   }
 
   // Helper: recursively rename deprecated icon strings inside an expression
-  function renameInExpression(node) {
+  /** @returns {boolean} */
+  function renameInExpression(/** @type {any} */ node) {
     if (!node) return false;
     let changed = false;
     if (node.type === 'StringLiteral' || node.type === 'Literal') {
@@ -67,7 +74,7 @@ export default function transformer(file, api) {
   }
 
   // 1. JSX attributes: icon="checkCircle" or icon={cond ? 'checkCircle' : 'copy'}
-  root.find(j.JSXAttribute).forEach((path) => {
+  root.find(j.JSXAttribute).forEach((/** @type {any} */ path) => {
     const attrName = path.node.name?.name;
     if (!ICON_PROPS.has(attrName)) return;
 
@@ -92,7 +99,7 @@ export default function transformer(file, api) {
 
   if (looksLikeIconRegistry) {
     const PropertyType = j.ObjectProperty ?? j.Property;
-    root.find(PropertyType).forEach((path) => {
+    root.find(PropertyType).forEach((/** @type {any} */ path) => {
       const key = path.node.key;
       if (!key) return;
       const keyName =
@@ -110,7 +117,7 @@ export default function transformer(file, api) {
   // 3. String literals in objects with icon-related keys
   //    e.g. { label: "TestX", href: "/pages/testx", icon: "checkCircle" }
   const PropertyType2 = j.ObjectProperty ?? j.Property;
-  root.find(PropertyType2).forEach((path) => {
+  root.find(PropertyType2).forEach((/** @type {any} */ path) => {
     const key = path.node.key;
     const keyName = key?.type === 'Identifier' ? key.name : key?.value;
     if (!ICON_PROPS.has(keyName)) return;