jscodeshift

New: Choose your parser

Problem: jscodeshift uses Babel v5 to parse source files. Since Babel v5 doesn't get updated anymore, jscodeshift is unable to parse files that contain more modern flow type annotation.

To solve this, jscodeshift now supports three parsers, babel v5, babylon and flow, and even allows you to pass your own. Babel v5 still stays the default parser, but we will likely use another parser (babylon or flow) as default in the future. Having the option to pass a custom parser allows us to experiment which works best with jscodeshift/recast.

How to choose a parser

CLI

--parser allows you specify one of the built-in parsers from the command line: --parser=babelv5, --parser=babylon, --parser=flow.

API

jscodeshift now accepts a second argument that is directly passed to recast's parse method. This allows you to load your own parser, as long as it is compatible with recast:

jscodeshift(source, {parser: require('myParser')})

Transformer

The value of the parser export of the transformer is used as parser. The value can either be the name of one of the built-in parsers (babel, babylon, flow) or an object that can be directly passed to recast.parse.

Examples:

export const parser = 'flow';
// or
export {default as parser} from 'myParser';

This allows transformers to specify their own parser (as long as it is compatible with ESTree / recast), making them a bit more independent from jscodeshift's internals.

jscodeshift --version now also lists the versions of the built-in parsers

$ jscodeshift --version
jscodeshift: 0.3.21
 - babel: 5.8.38
 - babylon: 6.8.1
 - flow: 0.26.0

Reinstalling jscodeshift is probably the simplest way for now to update the built-in parsers.

New

• --ignore-pattern and --ignore-file command line arguments, which allow you to specify paths to ignore when using jscodeshift to traverse over a dictionary ( #107 , @chrisdarroch )

• jscodeshift.use which you can pass a plugin too. A plugin would a function that accepts a jscodeshift instance and calls registerMethods on it. This allows plugins to be decoupled form jscodeshift. In addition, if .use is called with the same plugin multiple times, subsequent calls are ignored.

  Example:

  function myPlugin(jscodeshift) {
    jscodeshift.registerMethods({
      myExtension() { ... },
    }, jscodeshift.Identifier);
  }
  
  jscodeshift.use(myPlugin);
  

  ( #108 , @jamestalmage )

• Better registerMethods method! Until now, it was impossible to register two methods with the same name, even if it was attached to different types (and therefore, conceptually, different collections). @jamestalmage changed this in #110 and and now it's possible to register such methods if the types are not super- or sub-types.

  Example:

  jscodeshift.registerMethods({
    rename() { ... },
  }, j.Identifier);
  
  jscodeshift.registerMethods({
    rename() { ... },
  }, j.VariableDeclarator);
  

• Unit tests for transforms: @Daniel15 added helper methods to make writing unit tests easier ( #104 ) . See the readme and the example for more information.

  This results in a directory structure like this:

    /MyTransform.js
    /__tests__/MyTransform-test.js
    /__testfixtures__/MyTransform.input.js
    /__testfixtures__/MyTransform.output.js
  

  To define a test, use defineTest from the testUtils module:

    jest.autoMockOff();
    const defineTest = require('jscodeshift/dist/testUtils').defineTest;
    defineTest(__dirname, 'MyTransform');
  

Fixes

• Fixed hanging worker processes under certain conditions (we weren't able to find out the exact reasons but it looks like it involves processing at least 75 files) ( #102 ).
• Added missing line breaks to CLI output.

Internals

• Switched to jest 0.9.2.

Fixes

Fixed log output ( #101 )

Fixes

Both jscodeshift -t ... foo and jscodeshift -t ... foo/ work now ( #100 )

Fixes

• Installation issue (missing module)
• Typo (process.std vs process.stdout)

New

@iamdustan added supported for passing URLs to -t to load transforms remotely ( #94, #95 )

jscodeshift -t http://path/to/script.js

Note: That script cannot have any external dependencies, it has to be entirely self-contained.

Fixes

• Fix run-in-band ( #96, @zertosh )

Improvements

@avikchaudhuri improved invalid symlink handling ( #92 ) and worker performance ( #93 )!

Fixes

Ignore local .babelrc files. This fixes issues with running jscodeshift on code that was in a project that uses Babel. ( #85 ). Thanks to @sviridov!

Fixes

Fixed filtering for .closest method ( #83). Thanks @juliankrispel!

New

The --slient / -s option suppresses logging to the console ( #79 , #60 ).

New

--run-in-band option makes jscodeshift execute all transformations in the main process instead of splitting up over multiple workers. Useful for debugging. (#71, @zertosh)

Fixes

• Fixed promise (chain) returned by .run (#69). The code used to perform an invalid operation which let the promise fail always.

Improvements

• jscodeshift.match and many methods that accept an object as second argument for filtering / pattern matching (e.g. .find) now also accept functions / objects containing functions. This allows you to write more complex filters more easily.

  Example:

  j(source)
  .find(j.VariableDeclarator, {id: node => node.name === 'foo' || node.name === 'bar'})
  

finds all VariableDeclarators whose identifier is either named "foo" or "bar".

Internal changes

jscodeshift switched to jest v0.5.10, which means that tests will only run in Node v4+. jscodeshift will likely continue to function in older Node versions though.

New

• .run returns a promise that is resolved once all workers are done
• .at accepts negative indexes to get a collection of a node from the end of the current collection

Fixes

.remove now returns the collection itself

Fixes

• Fix .closest not correctly applying filter argument (#41)

Fixes

• File extension filter only applies to files in traversed directories, not to directly passed files
• Enforce latest recast version that fixes some printing issues
• Remove esprima-fb dependency

Changes

• Depend on babel-core instead of babel

Fixes

• No worker spawned when using --cpu option.

Fixes

• Printing options not passed along to root
• Trailing and leading whitespace being removed from file (#28)

Fixes

• Really fixed install process