Skip to content

A collection of codemods to help you upgrade carbon-react

License

Notifications You must be signed in to change notification settings

Sage/carbon-codemod

Repository files navigation

carbon-codemod npm

This is a collection of codemods that help you upgrade to a new version of carbon-react. The release notes of carbon-react will indicate which codemod you should use.

Usage

npx carbon-codemod <name-of-codemod> <target>

Note that <target> is worked out relative to the current working directory.

Make sure that the codemod is not being run in a folder containing a package.json file, as it may fail reporting missing dependencies.

For TypeScript codebase conversion use the --typescript option:

npx carbon-codemod <name-of-codemod> <target> --typescript

List of codemods with TypeScript support:

Development

carbon-codemod is a wrapper around jscodeshift.

Running locally

  • npm link
  • cd my-other-project
  • npm link carbon-codemod
  • npx carbon-codemod <name-of-codemod> <target>

Debugging

To debug the CLI

  • node --inspect-brk ./bin/carbon-codemod
  • Open the command palette and select "> Debug: Attach to Node Process (preview)"
  • You can add addition arguments as required e.g. node --inspect-brk ./bin/carbon-codemod --version

It's also possible to debug the tests

  • Open the spec file
  • Use Run Current Spec in the "Run" pane
  • You can use the "Debug Console" to interact with the debugger

You can use astexplorer.net to help understand the existing structure of files. You should use the following settings:

  • parser: esprima for js or @babel/parser for TypeScript
  • transform: jscodeshift

Transformation Status

The return value of the function determines the status of the transformation:

Status Condition Successful
ok A string is returned and it is different from passed source
skipped If nothing is returned, the file is not supposed to be transformed
unmodified If a string is returned but it's the same as the source
error If the transform throws an Exception

Testing

  • npm test
  • It's important to test that each codemod is idempotent.
  • Use defineTest to write new tests, this will create a fixture test and an idempotent test.
  • A codemod should convert both javascript and TypeScript projects.

Releasing

  • This project publishes using semantic-release.
  • It follows conventional commits.
  • When a pull request is merged to master Github Actions will run semantic-release.
  • semantic-release will decide, based on the commits that have been merged, if a new release is required.
  • If a new release is required, a new version will be published to npm and GitHub releases.