@wise/wds-codemods 0.0.1-experimental-6c2101b

package/src/transforms/helpers/__tests__/packageValidation.test.ts

@@ -0,0 +1,45 @@
+import type { Options } from 'jscodeshift';
+
+import { validatePackageRequirements } from '../packageValidation';
+
+describe('validatePackageRequirements', () => {
+  const requirements = [{ name: '@transferwise/components', version: '>=46.5.0' }];
+
+  beforeEach(() => {
+    jest.spyOn(console, 'debug').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('returns true when package is found (object format)', () => {
+    const options: Options = {
+      packageResults: { '@transferwise/components@>=46.5.0': true },
+    };
+
+    expect(validatePackageRequirements(options, requirements)).toBe(true);
+  });
+
+  it('returns true when package is found (JSON string format)', () => {
+    const options: Options = {
+      packageResults: '{"@transferwise/components@>=46.5.0":true}',
+    };
+
+    expect(validatePackageRequirements(options, requirements)).toBe(true);
+  });
+
+  it('returns false when package is missing', () => {
+    const options: Options = {
+      packageResults: { '@transferwise/components@>=46.5.0': false },
+    };
+
+    expect(validatePackageRequirements(options, requirements)).toBe(false);
+  });
+
+  it('returns false when no packageResults provided', () => {
+    const options: Options = {};
+
+    expect(validatePackageRequirements(options, requirements)).toBe(false);
+  });
+});

package/src/transforms/helpers/createTestTransform.ts

@@ -0,0 +1,59 @@
+import type { Options, Transform } from 'jscodeshift';
+import { applyTransform, type TestOptions } from 'jscodeshift/src/testUtils';
+
+interface PackageRequirement {
+  name: string;
+  version: string;
+  found?: boolean; // Optional - defaults to true
+}
+
+/**
+ * This function creates a test transform function that applies a given transformer to the input code.
+ * It uses the 'tsx' parser to support both TypeScript and JSX syntax.
+ *
+ * The transform function is used to modify the input code based on the provided transformer.
+ *
+ * @param transformer - The jscodeshift transformer function
+ * @param packageRequirements - Array of package requirements to mock (defaults to empty array)
+ */
+function createTestTransform(
+  transformer: Transform,
+  packageRequirements: PackageRequirement[] = [],
+) {
+  // Create mock package results from requirements
+  const packageResults: Record<string, boolean> = {};
+  packageRequirements.forEach((pkg) => {
+    const key = `${pkg.name}@${pkg.version}`;
+    packageResults[key] = pkg.found ?? true; // Default to found unless explicitly set to false
+  });
+
+  const options: Options = {
+    // Only add packageResults if we have package requirements
+    ...(packageRequirements.length > 0 ? { packageResults: JSON.stringify(packageResults) } : {}),
+  };
+
+  // Use 'tsx' parser to support both TypeScript and JSX syntax
+  const testOptions: TestOptions = { parser: 'tsx' };
+
+  return (input: { path?: string; source: string }) =>
+    applyTransform(transformer, options, input, testOptions);
+}
+
+// Convenience functions for common use cases
+export const createTestTransformWithPackage = (
+  transformer: Transform,
+  packageName: string,
+  version: string,
+) => {
+  return createTestTransform(transformer, [{ name: packageName, version }]);
+};
+
+export const createTestTransformWithoutPackage = (
+  transformer: Transform,
+  packageName: string,
+  version: string,
+) => {
+  return createTestTransform(transformer, [{ name: packageName, version, found: false }]);
+};
+
+export default createTestTransform;

package/src/transforms/helpers/hasImport.ts

@@ -0,0 +1,60 @@
+import type { Collection, JSCodeshift } from 'jscodeshift';
+
+/**
+ * Checks if a specific import exists in the given root collection and provides
+ * a method to remove it if found.
+ */
+function hasImport(
+  root: Collection,
+  sourceValue: string,
+  importName: string,
+  j: JSCodeshift,
+): { exists: boolean; remove: () => void } {
+  const importDeclarations = root.find(j.ImportDeclaration, {
+    source: { value: sourceValue },
+  });
+
+  if (importDeclarations.size() === 0) {
+    return {
+      exists: false,
+      remove: () => {},
+    };
+  }
+
+  const namedImport = importDeclarations.find(j.ImportSpecifier, {
+    imported: { name: importName },
+  });
+
+  const defaultImport = importDeclarations.find(j.ImportDefaultSpecifier, {
+    local: { name: importName },
+  });
+
+  const exists = namedImport.size() > 0 || defaultImport.size() > 0;
+
+  const remove = () => {
+    importDeclarations.forEach((path) => {
+      const filteredSpecifiers =
+        path.node.specifiers?.filter((specifier) => {
+          if (specifier.type === 'ImportSpecifier' && specifier.imported.name === importName) {
+            return false;
+          }
+          if (specifier.type === 'ImportDefaultSpecifier' && specifier.local?.name === importName) {
+            return false;
+          }
+          return true;
+        }) ?? [];
+
+      if (filteredSpecifiers.length === 0) {
+        path.prune();
+      } else {
+        j(path).replaceWith(
+          j.importDeclaration(filteredSpecifiers, path.node.source, path.node.importKind),
+        );
+      }
+    });
+  };
+
+  return { exists, remove };
+}
+
+export default hasImport;

package/src/transforms/helpers/iconUtils.ts

@@ -0,0 +1,87 @@
+import type { JSCodeshift, JSXElement, JSXExpressionContainer } from 'jscodeshift';
+
+/**
+ * Process children of a JSX element to detect icon components and add iconStart or iconEnd attributes accordingly.
+ * This is specific to icon handling but can be reused in codemods dealing with icon children.
+ */
+const processIconChildren = (
+  j: JSCodeshift,
+  children: (JSXElement | JSXExpressionContainer | unknown)[] | undefined,
+  iconImports: Set<string>,
+  openingElement: JSXElement['openingElement'],
+) => {
+  if (!children || !openingElement.attributes) return;
+
+  const unwrapJsxElement = (node: unknown): JSXElement | unknown => {
+    if (
+      typeof node === 'object' &&
+      node !== null &&
+      'type' in node &&
+      node.type === 'JSXExpressionContainer' &&
+      j.JSXElement.check((node as JSXExpressionContainer).expression)
+    ) {
+      return (node as JSXExpressionContainer).expression;
+    }
+    return node;
+  };
+
+  const totalChildren = children.length;
+
+  // Find index of icon child
+  const iconChildIndex = children.findIndex((child) => {
+    const unwrapped = unwrapJsxElement(child);
+    return (
+      j.JSXElement.check(unwrapped) &&
+      unwrapped.openingElement.name.type === 'JSXIdentifier' &&
+      iconImports.has(unwrapped.openingElement.name.name)
+    );
+  });
+
+  if (iconChildIndex === -1) return;
+
+  const iconChild = unwrapJsxElement(children[iconChildIndex]) as JSXElement;
+
+  if (!iconChild || iconChild.openingElement.name.type !== 'JSXIdentifier') return;
+
+  const iconName = iconChild.openingElement.name.name;
+
+  // Determine if icon is closer to start or end
+  const distanceToStart = iconChildIndex;
+  const distanceToEnd = totalChildren - 1 - iconChildIndex;
+  const iconPropName = distanceToStart <= distanceToEnd ? 'addonStart' : 'addonEnd';
+
+  // Build: { type: 'icon', value: <IconName /> }
+  const iconObject = j.objectExpression([
+    j.property('init', j.identifier('type'), j.literal('icon')),
+    j.property('init', j.identifier('value'), iconChild),
+  ]);
+  const iconProp = j.jsxAttribute(
+    j.jsxIdentifier(iconPropName),
+    j.jsxExpressionContainer(iconObject),
+  );
+
+  openingElement.attributes.push(iconProp);
+
+  // Remove the icon child
+  children.splice(iconChildIndex, 1);
+
+  // Helper to check if a child is whitespace-only JSXText
+  const isWhitespaceJsxText = (node: unknown): boolean => {
+    return (
+      typeof node === 'object' &&
+      node !== null &&
+      (node as { type?: unknown }).type === 'JSXText' &&
+      typeof (node as { value?: string }).value === 'string' &&
+      (node as { value?: string }).value!.trim() === ''
+    );
+  };
+
+  // Remove adjacent whitespace-only JSXText node if any
+  if (iconChildIndex - 1 >= 0 && isWhitespaceJsxText(children[iconChildIndex - 1])) {
+    children.splice(iconChildIndex - 1, 1);
+  } else if (isWhitespaceJsxText(children[iconChildIndex])) {
+    children.splice(iconChildIndex, 1);
+  }
+};
+
+export default processIconChildren;

package/src/transforms/helpers/index.ts

@@ -0,0 +1,5 @@
+export { default as hasImport } from './hasImport';
+export { default as processIconChildren } from './iconUtils';
+export * from './jsxElementUtils';
+export * from './jsxReportingUtils';
+export * from './packageValidation';

package/src/transforms/helpers/jsxElementUtils.ts

@@ -0,0 +1,67 @@
+import type {
+  JSCodeshift,
+  JSXAttribute,
+  JSXElement,
+  JSXIdentifier,
+  JSXMemberExpression,
+  JSXNamespacedName,
+  JSXSpreadAttribute,
+} from 'jscodeshift';
+
+/**
+ * Rename a JSX element name if it is a JSXIdentifier.
+ */
+export const setNameIfJSXIdentifier = (
+  elementName: JSXIdentifier | JSXNamespacedName | JSXMemberExpression | undefined,
+  newName: string,
+): JSXIdentifier | JSXNamespacedName | JSXMemberExpression | undefined => {
+  if (elementName && elementName.type === 'JSXIdentifier') {
+    return { ...elementName, name: newName };
+  }
+  return elementName;
+};
+
+/**
+ * Check if a list of attributes contains a specific attribute by name.
+ */
+export const hasAttribute = (
+  attributes: (JSXAttribute | JSXSpreadAttribute)[] | undefined,
+  attributeName: string,
+): boolean => {
+  return (
+    Array.isArray(attributes) &&
+    attributes.some(
+      (attr): attr is JSXAttribute =>
+        attr.type === 'JSXAttribute' &&
+        attr.name.type === 'JSXIdentifier' &&
+        attr.name.name === attributeName,
+    )
+  );
+};
+
+/**
+ * Check if a JSX element's openingElement has a specific attribute.
+ */
+export const hasAttributeOnElement = (
+  element: JSXElement['openingElement'],
+  attributeName: string,
+): boolean => {
+  return hasAttribute(element.attributes, attributeName);
+};
+
+/**
+ * Add specified attributes to a JSX element's openingElement if they are not already present.
+ */
+export const addAttributesIfMissing = (
+  j: JSCodeshift,
+  openingElement: JSXElement['openingElement'],
+  attributesToAdd: { attribute: JSXAttribute; name: string }[],
+) => {
+  if (!Array.isArray(openingElement.attributes)) return;
+  const attrs = openingElement.attributes;
+  attributesToAdd.forEach(({ attribute, name }) => {
+    if (!hasAttributeOnElement(openingElement, name)) {
+      attrs.push(attribute);
+    }
+  });
+};

package/src/transforms/helpers/jsxReportingUtils.ts

@@ -0,0 +1,224 @@
+import type { ASTPath, JSCodeshift, JSXAttribute, JSXElement, Node } from 'jscodeshift';
+
+export interface ReporterOptions {
+  jscodeshift: JSCodeshift;
+  issues: string[];
+}
+
+/**
+ * CodemodReporter is a utility class for reporting issues found during codemod transformations.
+ * It provides methods to report issues related to JSX elements, props, and attributes.
+ *
+ * @example
+ * ```typescript
+ * const issues: string[] = [];
+ * const reporter = createReporter(j, issues);
+ *
+ * // Report a deprecated prop
+ * reporter.reportDeprecatedProp(buttonElement, 'flat', 'variant="text"');
+ *
+ * // Report complex expression that needs review
+ * reporter.reportAmbiguousExpression(element, 'size');
+ *
+ * // Auto-detect common issues
+ * reporter.reportAttributeIssues(element);
+ * ```
+ */
+export class CodemodReporter {
+  private readonly j: JSCodeshift;
+  private readonly issues: string[];
+
+  constructor(options: ReporterOptions) {
+    this.j = options.jscodeshift;
+    this.issues = options.issues;
+  }
+
+  /**
+   * Reports an issue with a JSX element
+   */
+  reportElement(element: JSXElement | ASTPath<JSXElement>, reason: string): void {
+    const node = this.getNode(element);
+    const componentName = this.getComponentName(node);
+    const line = this.getLineNumber(node);
+
+    this.addIssue(`Manual review required: <${componentName}> at line ${line} ${reason}.`);
+  }
+
+  /**
+   * Reports an issue with a specific prop
+   */
+  reportProp(element: JSXElement | ASTPath<JSXElement>, propName: string, reason: string): void {
+    const node = this.getNode(element);
+    const componentName = this.getComponentName(node);
+    const line = this.getLineNumber(node);
+
+    this.addIssue(
+      `Manual review required: prop "${propName}" on <${componentName}> at line ${line} ${reason}.`,
+    );
+  }
+
+  /**
+   * Reports an issue with a JSX attribute directly
+   */
+  reportAttribute(
+    attr: JSXAttribute,
+    element: JSXElement | ASTPath<JSXElement>,
+    reason?: string,
+  ): void {
+    const node = this.getNode(element);
+    const componentName = this.getComponentName(node);
+    const propName = this.getAttributeName(attr);
+    const line = this.getLineNumber(attr) || this.getLineNumber(node);
+
+    const defaultReason = this.getAttributeReason(attr);
+    const finalReason = reason || defaultReason;
+
+    this.addIssue(
+      `Manual review required: prop "${propName}" on <${componentName}> at line ${line} ${finalReason}.`,
+    );
+  }
+
+  /**
+   * Reports spread props on an element
+   */
+  reportSpreadProps(element: JSXElement | ASTPath<JSXElement>): void {
+    this.reportElement(element, 'contains spread props that need manual review');
+  }
+
+  /**
+   * Reports conflicting prop and children
+   */
+  reportPropWithChildren(element: JSXElement | ASTPath<JSXElement>, propName: string): void {
+    this.reportProp(
+      element,
+      propName,
+      `conflicts with children - both "${propName}" prop and children are present`,
+    );
+  }
+
+  /**
+   * Reports unsupported prop value
+   */
+  reportUnsupportedValue(
+    element: JSXElement | ASTPath<JSXElement>,
+    propName: string,
+    value: string,
+  ): void {
+    this.reportProp(element, propName, `has unsupported value "${value}"`);
+  }
+
+  /**
+   * Reports ambiguous expression in prop
+   */
+  reportAmbiguousExpression(element: JSXElement | ASTPath<JSXElement>, propName: string): void {
+    this.reportProp(element, propName, 'contains a complex expression that needs manual review');
+  }
+
+  /**
+   * Reports ambiguous children (like dynamic icons)
+   */
+  reportAmbiguousChildren(element: JSXElement | ASTPath<JSXElement>, childType = 'content'): void {
+    this.reportElement(element, `contains ambiguous ${childType} that needs manual review`);
+  }
+
+  /**
+   * Reports deprecated prop usage
+   */
+  reportDeprecatedProp(
+    element: JSXElement | ASTPath<JSXElement>,
+    propName: string,
+    alternative?: string,
+  ): void {
+    const suggestion = alternative ? ` Use ${alternative} instead` : '';
+    this.reportProp(element, propName, `is deprecated${suggestion}`);
+  }
+
+  /**
+   * Reports missing required prop
+   */
+  reportMissingRequiredProp(element: JSXElement | ASTPath<JSXElement>, propName: string): void {
+    this.reportProp(element, propName, 'is required but missing');
+  }
+
+  /**
+   * Reports conflicting props
+   */
+  reportConflictingProps(element: JSXElement | ASTPath<JSXElement>, propNames: string[]): void {
+    const propList = propNames.map((name) => `"${name}"`).join(', ');
+    this.reportElement(element, `has conflicting props: ${propList} cannot be used together`);
+  }
+
+  /**
+   * Auto-detects and reports common attribute issues
+   */
+  reportAttributeIssues(element: JSXElement | ASTPath<JSXElement>): void {
+    const node = this.getNode(element);
+    const { attributes } = node.openingElement;
+
+    if (!attributes) return;
+
+    // Check for spread props
+    if (attributes.some((attr) => attr.type === 'JSXSpreadAttribute')) {
+      this.reportSpreadProps(element);
+    }
+
+    // Check for complex expressions in attributes
+    attributes.forEach((attr) => {
+      if (attr.type === 'JSXAttribute' && attr.value?.type === 'JSXExpressionContainer') {
+        this.reportAttribute(attr, element);
+      }
+    });
+  }
+
+  // Private helper methods
+  private getNode(element: JSXElement | ASTPath<JSXElement>): JSXElement {
+    return 'node' in element ? element.node : element;
+  }
+
+  private getComponentName(node: JSXElement): string {
+    const { name } = node.openingElement;
+    if (name.type === 'JSXIdentifier') {
+      return name.name;
+    }
+    // Handle JSXMemberExpression, JSXNamespacedName, etc.
+    return this.j(name).toSource();
+  }
+
+  private getLineNumber(node: JSXElement | JSXAttribute | Node): string {
+    return node.loc?.start.line?.toString() || 'unknown';
+  }
+
+  private getAttributeName(attr: JSXAttribute): string {
+    if (attr.name.type === 'JSXIdentifier') {
+      return attr.name.name;
+    }
+    return this.j(attr.name).toSource();
+  }
+
+  private getAttributeReason(attr: JSXAttribute): string {
+    if (!attr.value) return 'has no value';
+
+    if (attr.value.type === 'JSXExpressionContainer') {
+      const expr = attr.value.expression;
+      const expressionType = expr.type.replace('Expression', '').toLowerCase();
+
+      // Show actual value for simple cases
+      if (expr.type === 'Identifier' || expr.type === 'MemberExpression') {
+        const valueText = this.j(expr).toSource();
+        return `contains a ${expressionType} (${valueText})`;
+      }
+
+      return `contains a complex ${expressionType} expression`;
+    }
+
+    return 'needs manual review';
+  }
+
+  private addIssue(message: string): void {
+    this.issues.push(message);
+  }
+}
+
+export const createReporter = (j: JSCodeshift, issues: string[]): CodemodReporter => {
+  return new CodemodReporter({ jscodeshift: j, issues });
+};

package/src/transforms/helpers/packageValidation.ts

@@ -0,0 +1,53 @@
+import type { Options } from 'jscodeshift';
+
+interface PackageRequirement {
+  name: string;
+  version: string;
+}
+
+/**
+ * Check if package requirements are met
+ * Returns true if all packages are found, false otherwise
+ */
+export function validatePackageRequirements(
+  options: Options,
+  requirements: PackageRequirement[],
+): boolean {
+  let packageResults: Record<string, boolean> = {};
+
+  // Handle both string and object cases
+  if (options.packageResults) {
+    if (typeof options.packageResults === 'string') {
+      // Parse JSON string
+      try {
+        if (options.packageResults.trim() && options.packageResults.trim().startsWith('{')) {
+          packageResults = JSON.parse(options.packageResults) as Record<string, boolean>;
+        }
+      } catch (error) {
+        console.debug('Failed to parse packageResults:', error);
+        return false;
+      }
+    } else if (typeof options.packageResults === 'object') {
+      // Already an object, use directly
+      packageResults = options.packageResults as Record<string, boolean>;
+    }
+  }
+
+  // Check if all requirements are met
+  const allRequirementsMet = requirements.every((req) => {
+    const key = `${req.name}@${req.version}`;
+    return packageResults[key];
+  });
+
+  if (!allRequirementsMet) {
+    const missing = requirements.filter((req) => {
+      const key = `${req.name}@${req.version}`;
+      return !packageResults[key];
+    });
+
+    const missingPackages = missing.map((pkg) => `${pkg.name}@${pkg.version}`).join(', ');
+    console.debug(`Skipping transform - missing required packages: ${missingPackages}`);
+  }
+
+  return allRequirementsMet;
+}