Glossary

Codemod

Code that is written with the sole intent of transforming other code. An example would be a piece of code that takes a normal function, and rewrites it to be an arrow function.

– Reference

A codemod is a tool that can automatically refactor code. This can be particularly useful when making large-scale changes to a codebase, such as changing a function or method signature. Instead of manually updating every instance of the function, a codemod can do the work for you.

Codemods are often used to update code to be compatible with newer versions of a programming language or library. For example, if a library changes its API, a codemod can automatically update all of the code that uses the old API to use the new one. This saves time and helps ensure that the codebase stays up-to-date and consistent.

To use a codemod, you typically provide it with the old and new code, as well as the files or directories that you want to update. The codemod will then scan the code and make the necessary changes. Some codemods are simple and only make a single replacement, while others can perform more complex refactoring.

One important thing to note about codemods is that they are not perfect. Because they are automatically making changes to your code, there is always the potential for errors. It is important to carefully review the changes made by a codemod and fix any issues that may arise.

In summary, codemods are a useful tool for automatically refactoring code. They can save time and help ensure that your code stays up-to-date and consistent. However, it is important to carefully review the changes made by a codemod to avoid any potential errors.

For example, here is an example of a simple codemod that transforms the string "hello world" to "hello universe" using the JSCodeshift library:

const jscodeshift = require('jscodeshift');

module.exports = function transformer(file, api) {
  const j = api.jscodeshift;
  return j(file.source)
    .find(j.Literal)
    .filter(path => path.node.value === 'hello world')
    .replaceWith(() => j.literal('hello universe'))
    .toSource();
};

This codemod searches the code for literal values that equal "hello world" and replaces them with "hello universe". It uses the jscodeshift library to parse and transform the code, and then returns the modified code as a string.

Transform

A transform is simply a javascript function which serves as the entry-point for your codemod.

For example:

module.exports = function transformer(file, api) {
  //... codemod goes here
};

Motion

A motion (aka migration) is what we call specific actions performed within a codemod. Put simply, javascript functions that are responsible for a single action within a codemod.

For more information see: Authoring

AST

An abstract syntax tree (AST), is a tree representation of the abstract syntactic structure of source code written in a programming language. Each node of the tree denotes a construct occurring in the source code.

– Wiki: Abstract syntax tree

jscodeshift

jscodeshift is the underlying library used by Hypermod.

• Provides both a CLI for running transforms and a jQuery-like API for manipulating ASTs
• AST transformations are performed using a wrapper around recast.
• The AST is implemented in ast-types, which is itself based on esprima

recast

recast is the underlying library used by jscodeshift to parse, transform and output files as ASTs. It's a comparable library to babel

A fantastic library (authored by Ben Newman) that takes an AST and transforms it back into source code. The beauty of recast is that it tries to preserve as much of your codes existing formatting as possible.

– Reference

ast-types

ast-types

Another great library authored by Ben Newman. It exposes 2 kinds of helpers that you’ll be using: functions that allow you to verify assumptions about nodes, and functions that allow you to compose new nodes to be added to an existing AST.

– Reference

Node

The representation of a single construct within an AST. An example of a node could be a node for a FunctionExpression. A node will often have many other nodes nested within it.

– Reference

For more information see the jscodeshift docs

Path

An object that wraps a single node, and exposes an API to make modifying/inspecting information about the node simpler.

– Reference

For more information see the jscodeshift docs

Collection

A group of path objects that exposes helpers to transform all contained paths, or traverse them further. Collections are very similar to the object returned from jQuery’s \$() function.

– Reference

For more information see the jscodeshift docs

Builders

Builders are methods intended to create new AST nodes.

For example creating an import declaration with the importDeclaration() builder might look like this:

j.importDeclaration(
  [j.importDefaultSpecifier(j.identifier('Foo'))],
  j.stringLiteral('bar'),
);

For more information see the jscodeshift docs