GithubHelp home page GithubHelp logo

jscodeshift's Introduction

jscodeshift Support Ukraine Build Status

jscodeshift is a toolkit for running codemods over multiple JavaScript or TypeScript files. It provides:

  • A runner, which executes the provided transform for each file passed to it. It also outputs a summary of how many files have (not) been transformed.
  • A wrapper around recast, providing a different API. Recast is an AST-to-AST transform tool and also tries to preserve the style of original code as much as possible.

Install

Get jscodeshift from npm:

$ npm install -g jscodeshift

This will install the runner as jscodeshift.

VSCode Debugger

Configure VSCode to debug codemods

Usage (CLI)

The CLI provides the following options:

$ jscodeshift --help

Usage: jscodeshift [OPTION]... PATH...
  or:  jscodeshift [OPTION]... -t TRANSFORM_PATH PATH...
  or:  jscodeshift [OPTION]... -t URL PATH...
  or:  jscodeshift [OPTION]... --stdin < file_list.txt

Apply transform logic in TRANSFORM_PATH (recursively) to every PATH.
If --stdin is set, each line of the standard input is used as a path.

Options:
"..." behind an option means that it can be supplied multiple times.
All options are also passed to the transformer, which means you can supply custom options that are not listed here.

      --(no-)babel              apply babeljs to the transform file
                                (default: true)
  -c, --cpus=N                  start at most N child processes to process source files
                                (default: max(all - 1, 1))
  -d, --(no-)dry                dry run (no changes are made to files)
                                (default: false)
      --extensions=EXT          transform files with these file extensions (comma separated list)
                                (default: js)
  -h, --help                    print this help and exit
      --ignore-config=FILE ...  ignore files if they match patterns sourced from a configuration file (e.g. a .gitignore)
      --ignore-pattern=GLOB ...  ignore files that match a provided glob expression
      --parser=babel|babylon|flow|ts|tsx  the parser to use for parsing the source files
                                          (default: babel)
      --parser-config=FILE      path to a JSON file containing a custom parser configuration for flow or babylon
  -p, --(no-)print              print transformed files to stdout, useful for development
                                (default: false)
      --(no-)run-in-band        run serially in the current process
                                (default: false)
  -s, --(no-)silent             do not write to stdout or stderr
                                (default: false)
      --(no-)stdin              read file/directory list from stdin
                                (default: false)
  -t, --transform=FILE          path to the transform file. Can be either a local path or url
                                (default: ./transform.js)
  -v, --verbose=0|1|2           show more information about the transform process
                                (default: 0)
      --version                 print version and exit
      --fail-on-error           return a 1 exit code when errors were found during execution of codemods

This passes the source of all passed through the transform module specified with -t or --transform (defaults to transform.js in the current directory). The next section explains the structure of the transform module.

Usage (JS)

const {run: jscodeshift} = require('jscodeshift/src/Runner')

const transformPath = 'transform.js'
const paths = ['foo.js', 'bar']
const options = {
  dry: true,
  print: true,
  verbose: 1,
  // ...
}

const res = await jscodeshift(transformPath, paths, options)
console.log(res)
/*
{
  stats: {},
  timeElapsed: '0.001',
  error: 0,
  ok: 0,
  nochange: 0,
  skip: 0
}
*/

Transform module

The transform is simply a module that exports a function of the form:

module.exports = function(fileInfo, api, options) {
  // transform `fileInfo.source` here
  // ...
  // return changed source
  return source;
};

As of v0.6.1, this module can also be written in TypeScript.

Arguments

fileInfo

Holds information about the currently processed file.

Property Description
path File path
source File content

api

This object exposes the jscodeshift library and helper functions from the runner.

Property Description
jscodeshift A reference to the jscodeshift library
stats A function to collect statistics during --dry runs
report Prints the passed string to stdout

jscodeshift is a reference to the wrapper around recast and provides a jQuery-like API to navigate and transform the AST. Here is a quick example, a more detailed description can be found below.

/**
 * This replaces every occurrence of variable "foo".
 */
module.exports = function(fileInfo, api, options) {
  return api.jscodeshift(fileInfo.source)
    .findVariableDeclarators('foo')
    .renameTo('bar')
    .toSource();
}

Note: This API is exposed for convenience, but you don't have to use it. You can use any tool to modify the source.

stats is a function that only works when the --dry options is set. It accepts a string, and will simply count how often it was called with that value.

At the end, the CLI will report those values. This can be useful while developing the transform, e.g. to find out how often a certain construct appears in the source(s).

report allows you do print arbitrary strings to stdout. This can be useful when other tools consume the output of jscodeshift. The reason to not directly use process.stdout in transform code is to avoid mangled output when many files are processed.

options

Contains all options that have been passed to runner. This allows you to pass additional options to the transform. For example, if the CLI is called with

$ jscodeshift -t myTransforms fileA fileB --foo=bar

options would contain {foo: 'bar'}.

Return value

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

  • If a string is returned and it is different from passed source, the transform is considered to be successful.
  • If a string is returned but it's the same as the source, the transform is considered to be unsuccessful.
  • If nothing is returned, the file is not supposed to be transformed (which is ok).

The CLI provides a summary of the transformation at the end. You can get more detailed information by setting the -v option to 1 or 2.

You can collect even more stats via the stats function as explained above.

Parser

The transform file can let jscodeshift know with which parser to parse the source files (and features like templates).

To do that, the transform module can export parser, which can either be one of the strings "babel", "babylon", "flow", "ts", or "tsx", or it can be a parser object that is compatible with recast and follows the estree spec.

Example: specifying parser type string in the transform file

module.exports = function transformer(file, api, options) {
  const j = api.jscodeshift;
  const rootSource = j(file.source);
  
  // whatever other code...
  
  return rootSource.toSource();
}
  
// use the flow parser
module.exports.parser = 'flow'; 

Example: specifying a custom parser object in the transform file

module.exports = function transformer(file, api, options) {
  const j = api.jscodeshift;
  const rootSource = j(file.source);
  
  // whatever other code...
  
  return rootSource.toSource();
}

module.exports.parser = {
  parse: function(source) {
    // return estree compatible AST
  },
};

Example output

$ jscodeshift -t myTransform.js src
Processing 10 files...
Spawning 2 workers with 5 files each...
All workers done.
Results: 0 errors 2 unmodified 3 skipped 5 ok

The jscodeshift API

As already mentioned, jscodeshift also provides a wrapper around recast. In order to properly use the jscodeshift API, one has to understand the basic building blocks of recast (and ASTs) as well.

Core Concepts

AST nodes

An AST node is a plain JavaScript object with a specific set of fields, in accordance with the Mozilla Parser API. The primary way to identify nodes is via their type.

For example, string literals are represented via Literal nodes, which have the structure

// "foo"
{
  type: 'Literal',
  value: 'foo',
  raw: '"foo"'
}

It's OK to not know the structure of every AST node type. The (esprima) AST explorer is an online tool to inspect the AST for a given piece of JS code.

Path objects

Recast itself relies heavily on ast-types which defines methods to traverse the AST, access node fields and build new nodes. ast-types wraps every AST node into a path object. Paths contain meta-information and helper methods to process AST nodes.

For example, the child-parent relationship between two nodes is not explicitly defined. Given a plain AST node, it is not possible to traverse the tree up. Given a path object however, the parent can be traversed to via path.parent.

For more information about the path object API, please have a look at ast-types.

Builders

To make creating AST nodes a bit simpler and "safer", ast-types defines a couple of builder methods, which are also exposed on jscodeshift.

For example, the following creates an AST equivalent to foo(bar):

// inside a module transform
var j = jscodeshift;
// foo(bar);
var ast = j.callExpression(
  j.identifier('foo'),
  [j.identifier('bar')]
);

The signature of each builder function is best learned by having a look at the definition files.

Collections and Traversal

In order to transform the AST, you have to traverse it and find the nodes that need to be changed. jscodeshift is built around the idea of collections of paths and thus provides a different way of processing an AST than recast or ast-types.

A collection has methods to process the nodes inside a collection, often resulting in a new collection. This results in a fluent interface, which can make the transform more readable.

Collections are "typed" which means that the type of a collection is the "lowest" type all AST nodes in the collection have in common. That means you cannot call a method for a FunctionExpression collection on an Identifier collection.

Here is an example of how one would find/traverse all Identifier nodes with jscodeshift and with recast:

// recast
var ast = recast.parse(src);
recast.visit(ast, {
  visitIdentifier: function(path) {
    // do something with path
    return false;
  }
});

// jscodeshift
jscodeshift(src)
  .find(jscodeshift.Identifier)
  .forEach(function(path) {
    // do something with path
  });

To learn about the provided methods, have a look at the Collection.js and its extensions.

Extensibility

jscodeshift provides an API to extend collections. By moving common operators into helper functions (which can be stored separately in other modules), a transform can be made more readable.

There are two types of extensions: generic extensions and type-specific extensions. Generic extensions are applicable to all collections. As such, they typically don't access specific node data, but rather traverse the AST from the nodes in the collection. Type-specific extensions work only on specific node types and are not callable on differently typed collections.

Examples

// Adding a method to all Identifiers
jscodeshift.registerMethods({
  logNames: function() {
    return this.forEach(function(path) {
      console.log(path.node.name);
    });
  }
}, jscodeshift.Identifier);

// Adding a method to all collections
jscodeshift.registerMethods({
  findIdentifiers: function() {
    return this.find(jscodeshift.Identifier);
  }
});

jscodeshift(ast).findIdentifiers().logNames();
jscodeshift(ast).logNames(); // error, unless `ast` only consists of Identifier nodes

Passing options to recast

You may want to change some of the output settings (like setting ' instead of "). This can be done by passing config options to recast.

.toSource({quote: 'single'}); // sets strings to use single quotes in transformed code.

You can also pass options to recast's parse method by passing an object to jscodeshift as second argument:

jscodeshift(source, {...})

More on config options here

Unit Testing

jscodeshift comes with a simple utility to allow easy unit testing with Jest, without having to write a lot of boilerplate code. This utility makes some assumptions in order to reduce the amount of configuration required:

  • The test is located in a subdirectory under the directory the transform itself is located in (eg. __tests__)
  • Test fixtures are located in a __testfixtures__ directory

This results in a directory structure like this:

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

A simple example of unit tests is bundled in the sample directory.

The testUtils module exposes a number of useful helpers for unit testing.

defineTest

Defines a Jest/Jasmine test for a jscodeshift transform which depends on fixtures

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

An alternate fixture filename can be provided as the fourth argument to defineTest. This also means that multiple test fixtures can be provided:

defineTest(__dirname, 'MyTransform', null, 'FirstFixture');
defineTest(__dirname, 'MyTransform', null, 'SecondFixture');

This will run two tests:

  • __testfixtures__/FirstFixture.input.js
  • __testfixtures__/SecondFixture.input.js

defineInlineTest

Defines a Jest/Jasmine test suite for a jscodeshift transform which accepts inline values

This is a more flexible alternative to defineTest, as this allows to also provide options to your transform

const defineInlineTest = require('jscodeshift/dist/testUtils').defineInlineTest;
const transform = require('../myTransform');
const transformOptions = {};
defineInlineTest(transform, transformOptions, 'input', 'expected output', 'test name (optional)');

defineSnapshotTest

Similar to defineInlineTest but instead of requiring an output value, it uses Jest's toMatchSnapshot()

const defineSnapshotTest = require('jscodeshift/dist/testUtils').defineSnapshotTest;
const transform = require('../myTransform');
const transformOptions = {};
defineSnapshotTest(transform, transformOptions, 'input', 'test name (optional)');

For more information on snapshots, check out Jest's docs

defineSnapshotTestFromFixture

Similar to defineSnapshotTest but will load the file using same file-directory defaults as defineTest

const defineSnapshotTestDefault = require('jscodeshift/dist/testUtils').defineSnapshotTestDefault;
const transform = require('../myTransform');
const transformOptions = {};
defineSnapshotTestFromFixture(__dirname, transform, transformOptions, 'FirstFixture', 'test name (optional)');

applyTransform

Executes your transform using the options and the input given and returns the result. This function is used internally by the other helpers, but it can prove useful in other cases.

const applyTransform = require('jscodeshift/dist/testUtils').applyTransform;
const transform = require('../myTransform');
const transformOptions = {};
const output = applyTransform(transform, transformOptions, 'input');

ES modules

If you're authoring your transforms and tests using ES modules, make sure to import the transform's parser (if specified) in your tests:

// MyTransform.js
export const parser = 'flow'
export default function MyTransform(fileInfo, api, options) {
  // ...
}
// __tests__/MyTransform-test.js
import { defineInlineTest } from 'jscodeshift/dist/testUtils
import * as transform from '../MyTransform

console.log(transform.parser) // 'flow'

defineInlineTest(transform, /* ... */)

Example Codemods

  • react-codemod - React codemod scripts to update React APIs.
  • js-codemod - Codemod scripts to transform code to next generation JS.
  • js-transforms - Some documented codemod experiments to help you learn.
  • fix-js - Codemods to fix some ESLint issues

Local Documentation Server

To update docs in /docs, use npm run docs.

To view these docs locally, use npx http-server ./docs

VSCode Debugging

It's recommended that you set up your codemod project to all debugging via the VSCode IDE. When you open your project in VSCode, add the following configuration to your launch.json debugging configuration.

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "pwa-node",
            "request": "launch",
            "name": "Debug Transform",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "program": "${workspaceRoot}/node_modules/.bin/jscodeshift",
            "stopOnEntry": false,
            "args": ["--dry", "--print", "-t", "${input:transformFile}", "--parser", "${input:parser}", "--run-in-band", "${file}"],
            "preLaunchTask": null,
            "runtimeExecutable": null,
            "runtimeArgs": [
                "--nolazy"
            ],
            "console": "internalConsole",
            "sourceMaps": true,
            "outFiles": []
        },
        {
            "name": "Debug All JSCodeshift Jest Tests",
            "type": "node",
            "request": "launch",
            "runtimeArgs": [
                "--inspect-brk",
                "${workspaceRoot}/node_modules/jest/bin/jest.js",
                "--runInBand",
                "--testPathPattern=${fileBasenameNoExtension}"
            ],
            "console": "integratedTerminal",
            "internalConsoleOptions": "neverOpen",
            "port": 9229
        }
    ],
    "inputs": [
        {
          "type": "pickString",
          "id": "parser",
          "description": "jscodeshift parser",
          "options": [
            "babel",
            "babylon",
            "flow",
            "ts",
            "tsx",
          ],
          "default": "babel"
        },
        {
            "type": "promptString",
            "id": "transformFile",
            "description": "jscodeshift transform file",
            "default": "transform.js"
        }
    ]
}

Once this has been added to the configuration

  1. Install jscodeshift as a package if you haven't done so already by running the command npm install --save jscodeshift. The debug configuration will not work otherwise.
  2. Once the jscodeshift local package has been installed, go to the VSCode file tree and select the file on which you want to run the transform. For example, if you wanted to run codemod transforms of foo.js file, you would click on the entry for foo.js file in your project tree.
  3. Select "Debug Transform" from the debugging menu's options menu.
  4. Click the "Start Debugging" button on the VSCode debugger.
  5. You will be then prompted for the name of jscodeshift transform file. Enter in the name of the transform file to use. If no name is given it will default to transform.js
  6. Select the parser to use from the presented selection list of parsers. The transform will otherwise default to using the babel parser.
  7. The transform will then be run, stopping at any breakpoints that have been set.
  8. If there are no errors and the transform is complete, then the results of the transform will be printed in the VSCode debugging console. The file with the contents that have been transformed will not be changed, as the debug configuration makes use the jscodeshift --dry option.

Recipes

jscodeshift's People

Contributors

abernier avatar alangpierce avatar avikchaudhuri avatar baopham avatar brieb avatar cjlarose avatar cpojer avatar daniel15 avatar dependabot[bot] avatar drewml avatar dsainati1 avatar elonvolo avatar eventualbuddha avatar fkling avatar gkz avatar iamdustan avatar jamestalmage avatar jbrown215 avatar jedwards1211 avatar jhilker avatar lencioni avatar marcodejongh avatar nickmccurdy avatar sharils avatar trivikr avatar vjeux avatar wincent avatar xixixao avatar yungsters avatar zertosh avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

jscodeshift's Issues

Possible to flatten?

Sometimes I want to flatten a collection. For example, I may get a CallExpression's arguments and want to act on each of them. Is this easy/possible now, or could we have a flatMap?

Re-use old AST

When transforming the AST, it would be useful to re-use part of the old AST so I don't have to manually reconstruct all nodes nested in the part I'm transforming:

module.exports = function(file, api) {
  const j = api.jscodeshift;
  const {expression, statement, statements} = j.template;

  return j(file.source)
    .find(j.Identifier)
    .replaceWith(
      p => j.memberExpression(j.identifier('foo'), p)
    )
    .toSource();
};

Is this possible?

Newlines stripped from processed files

new lines seem to be removed even if i dont change a file, for now i am having to do:

return root.toSource({quote: 'single', trailingComma: true}) + '\n';

Maybe this is an issue with recast?

[Traversals] Add `closestScope`

A closestScope function would return the closest scope (walking up the parent nodes) which is either a function, arrow function, method declaration, function declaration or function expression (and maybe others).

This is something that has come up repeatedly for me when trying to trace identifiers or other things around in an AST.

Example of where I did the traversal manually: cpojer/[email protected]a20a5e1

Resolve the new file contents from the runner

I'm writing tests for my codemod and want to use the runner programmatically instead of shelling out. I have two fixture files, a before and an after. I want to dry-run the before file, get the output and compare it to my after file.

However, when running the runner programmatically with dry run, I don't believe there is any way to receive the new file. The runner should probably resolve an object that contains information about how long it took to run and the new content.

Restructure runner and logging

Instead of using console.log, the runner should write to stdout and stderr, or maybe to streams passed to it. Either way, the runner shouldn't output anything, but return information about the progress / result to the caller, one way or the other.

The caller (e.g. the jscodeshift binary) can then decide how to deal with this information and also set proper exit codes.

jscodeshift Using .babelrc project file incorrectly in Babel 6 Environments

Scenario:

  • Project using Babel 6, and .babelrc file for project configuration
  • Babel 6 installed globally
  • jscodeshift is run within the project directory at the same level as the .babelrc file

Result:

/usr/local/lib/node_modules/jscodeshift/node_modules/babel-core/lib/transformation/file/options/option-manager.js:126
      if (!option) this.log.error("Unknown option: " + alias + "." + key, ReferenceError);
                           ^

TypeError: Cannot read property 'error' of undefined
    at OptionManager.mergeOptions (/usr/local/lib/node_modules/jscodeshift/node_modules/babel-core/lib/transformation/file/options/option-manager.js:126:28)
    at OptionManager.addConfig (/usr/local/lib/node_modules/jscodeshift/node_modules/babel-core/lib/transformation/file/options/option-manager.js:107:10)
    at OptionManager.findConfigs (/usr/local/lib/node_modules/jscodeshift/node_modules/babel-core/lib/transformation/file/options/option-manager.js:168:35)
    at OptionManager.init (/usr/local/lib/node_modules/jscodeshift/node_modules/babel-core/lib/transformation/file/options/option-manager.js:229:12)
    at compile (/usr/local/lib/node_modules/jscodeshift/node_modules/babel-core/lib/api/register/node.js:117:22)
    at normalLoader (/usr/local/lib/node_modules/jscodeshift/node_modules/babel-core/lib/api/register/node.js:199:14)
    at Object.require.extensions.(anonymous function) [as .js] (/usr/local/lib/node_modules/jscodeshift/node_modules/babel-core/lib/api/register/node.js:216:7)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:311:12)
    at Module.require (module.js:366:17)

Temporary fix:

  • Run jscodeshift from outside the project directory, with no .babelrc file in the directory you are running jscodeshift within.

templates evaluate at global scope, breaks statement`return;`

Return statements can only be added inside a function but templates are evaluated by babel at the global scope so babel throws on

statement`return;`

Example: http://felix-kling.de/esprima_ast_explorer/#/1lLYuPcGmT

This also happens for break; statements as well.

@fkling had an idea of always evaluating templates within a function but that could break things like import that can only be added at the global scope. Not sure what the way forward is here but i find the templating extremely valuable so it would be great to find a solution!

Replacement of nodes contained in others nodes already replaced

Hi,

I think there might be something not working well, maybe in jscodeshift or in recast, but not completely sure yet. The case is when you try to replace a node A which is contained in another B. B has already been replaced. It uses strings as replacements in A and B. This is the example (this transformer is intended to add a trailing comma at the end of every property in object expressions): http://astexplorer.net/#/fU8E4pJxdx/4

The expected value would be:

var x = {
    b: function(){
        var z = {
          b: 3,
          c: 1,
        };
    },
    d: 2,
};

var y = {
    i: 2,
};

But as you can see, c: 1 does not contain a comma at the end in the example. I have tried it locally and the same happens. Doing some logging, the transformer passes through the replaceWith function related with the

{
  b: 3,
  c: 1
}

after the replacement of the container ObjectExpression, and everything seems to be working fine, so it should be replacing it but the final result does not contain it. Any ideas? Am I missing something?

Allow excluding subdirectories like node_modules

I'd like to run a mod on a large directory of directories, each of which can have a 'node_modules' directory I'd like to ignore. It'd be great to have an option in jscodeshift to exclude subdirectory patterns if you pass it a directory to transform.

Class decorators are dropped

After running this transform jscodeshift ate up all my class decorators e.g.:

@connect(data => getDataProps(data))
class Screen extends React.Component {
}

became

class Screen extends React.Component {
}

Reprinting file without changes line break changes

Parsing and reprinting

// I have a parent
newNode.parent
  && (
    (// Or I did but its different than the one I have now.
      !originalNode.parent ||
      newNode.parent.key !== originalNode.parent.key
    )
  )

outputs

// I have a parent
newNode.parent
  && (
    (// Or I did but its different than the one I have now.
      (!originalNode.parent || newNode.parent.key !== originalNode.parent.key)
    )
  )

which is inconvenient for codemods. Live test: http://felix-kling.de/esprima_ast_explorer/#/NvtYJQH95L.

Silent mode

I'm writing tests for my codemods and thus running jscodeshift repeatedly in my tests. There is a lot of information printed for every run:

Processing 1 files...
Spawning 1 workers with 1 files each...
Running in dry mode, no files will be written!
All workers done.
Results: 0 errors 0 unmodifed 0 skipped 1 ok
Time elapsed: 0.902 seconds

It would be nice if there was a silent mode. The information printed could be provided as a data object at the end as per #59

Add support for config files

Proposal

Teach the binary to accept a --config option

This option would allow you to specify a config file on disk from which additional options would be read. The file would contain additional options to be included with the invocation; for example:

--cpus 2 -v

Options explicitly provided on the command-line would override options read from the config file. For example, given the config above, --cpus would be set to 4 for an invocation like this:

jscodeshift --config my-config --cpus 4 target.js

In the absence of a --config option, look for config in default locations

Default locations could be:

  • .jscodeshiftrc in current directory
  • $HOME/.jscodeshiftrc
  • /etc/jscodeshiftrc (or something like that)

This would, for example, enable you to provide a consistent set of Recast printOptions that you would use, by convention, in all of your transform scripts (ie. in the call to toSource()).

Considerations

Do we want the config file to be just a dumb string that we split and pass into nomnom as though the args were passed on the commandline? Or do we prefer a more structured format (like JSON) which would allow us to pass richer configuration objects rather than just scalar values (strings, numbers, bools)? I'm inclined to think the latter, so that we could configure things like printOptions for Recast with:

{
  'cpus': 2,
  'v': true,
  'printOptions': {'quote': 'single'}
}

Make `map` on Collections work with nodes

This should work:

  const findReactCreateClassExportDefault = path =>
    path
      .find(j.ExportDefaultDeclaration, {
        type: 'ExportDefaultDeclaration',
        declaration: {
          type: 'CallExpression',
          callee: REACT_CREATE_CLASS_MEMBER_EXPRESSION
        }
      })
      .map((p) => {
        return p.value.declaration;
      })

cc @iammerrick

Ignoring "empty" files

Empty files, or files with no code (empty, or just breakline) will throw errors while transforming...

ERR  /javascript/foo.js Transformation error
TypeError: Cannot read property 'line' of null
    at Object.exports.fixFaultyLocations (/node_modules/recast/lib/util.js:142:22)
    at TreeCopier.TCp.copy (/node_modules/recast/lib/parser.js:98:10)
    at TreeCopier.TCp.copy (/node_modules/recast/lib/parser.js:135:30)
    at Object.parse (/repo/aura-codemod/node_modules/recast/lib/parser.js:78:34)
    at fromSource (/repo/aura-codemod/node_modules/jscodeshift/dist/core.js:72:25)

I suspect that it is jscodeshift the one reading from disk, and just passing the empty content to recast, that's why I'm opening the issue in this repo.

Note: why are those files empty is not important, but should not be an indication of error, at the end of the day, they are valid javascript source.

How to convert to a `NodePath`?

I'm trying to create a transformer that will go from:

React.createElement(Foo, null);
React.createElement(Foo, { bar: "baz", onClick: this.divClicked });

React.createElement(
    Foo,
    { bar: "baz", onClick: this.divClicked },
    React.createElement("div", { foo: "bar" })
  );

to

<Foo></Foo>;
<Foo bar="baz" onClick={this.divClicked}></Foo>;

<Foo bar="baz" onClick={this.divClicked}>
    <div foo="bar">
    </div>
</Foo>

I've gotten the first two examples, but I'm confused on recursively handling the children.

My interactive codemod is here: http://felix-kling.de/esprima_ast_explorer/#/hb6iLO9hTe/4

If I change convertNodeToJSX to:

function convertNodeToJSX(node) { 
    if (!node) {
      return;
    }

    console.log(node);

   // other code

   const children = convertNodeToJSX(args[2]);

then I get printed out

NodePath {value: Object, parentPath: NodePath, name: "expression", __childCache: Object}
NodePath {value: Object, parentPath: NodePath, name: "expression", __childCache: Object}
NodePath {value: Object, parentPath: NodePath, name: "expression", __childCache: Object}
Object {type: "CallExpression", start: 175, end: 217, loc: i, callee: Object…}

So how can I convert the CallExpression to a NodePath? Wrapping the element with j() gives me:

e {_parent: undefined, __paths: Array[1], _types: Array[5]}

Or perhaps as a higher level question, is this even the right approach?

File comment is lost when removing first statement

If you have

/**
 * @providesModule Foo.react
 */

var React = require('React');

and remove the require statement, the docblock is lost. This causes build errors and I had to manually fix up a bunch of files with the last codemod I wrote to restore these.

Collection.reverse

I wonder if we could add a reverse helper on to the collection class. Currently I'm doing this:

const reverseCollection = collection => j(collection.paths().reverse());

I need to reverse the collection to perform operations on nested call expressions, so I can start at the deep end and traverse up, copying across old nodes as I please.

Transform a directory of files

jscodeshift html/js --extensions=js,jsx should transform all files recursively in the passed in directory that match the extensions option.

closest's second argument doesn't appear to work

Here's an example: http://felix-kling.de/esprima_ast_explorer/#/WhIlcdMzwh/1

function foo() {
  function bar() {
    return 3;
  }
}
module.exports = function(file, api) {
  var j = api.jscodeshift;

  return j(file.source)
    .find(j.Literal)
    .forEach(function(path) { console.log(path.value) })
    .closest(j.FunctionDeclaration, { id: { name: "foo" } })
    .forEach(function(path) { 
      console.log(path.value);
      path.value.id.name = 'renamed'; })
    .toSource();
};

I'd expect this to work like find does, using the 2nd parameter as a filter. Unfortunately, adding the 2nd parameter causes it to find the ReturnStatement instead of the top level Foo function

Copy indentation and comments across to new nodes

I am regenerating nodes but I would like to retain indentation and comments for those nodes, i.e.

foo
  .baz // bob
  .bar

If I process this:

j(file.source)
    .find(j.MemberExpression)
    .replaceWith(
      p => j.memberExpression(p.node.object, p.node.property)
    )
    .toSource()

I get:

foo.baz.bar

As in http://astexplorer.net/#/RKmXYV9kFT/1

Is there a way to retain indentation and comments? Keeping in mind that sometimes I might need to rename things.

How to find root member expression?

How can I find usages of _.chain(x).y().z()…, like so:

var foo = [];
var x = _.chain(foo)
    .map(function () { return x; })
    .filter(function () { return x; })
    .value();

where I don't know how many methods will be called?

The closest I've come is to finding the MemberExpression of _.chain, but I need to find the entire expression that is being assigned to x. Furthermore, I want to match usages of _.chain in other contexts, such as CallExpressions:

foo(_.chain([]).map(x => x));

My goal is to build a list of all the methods being called on _.chain(foo), i.e. map, filter, value.

Bake in ability to preprocess the transform script

The motivating use case here is the ability to transform the transform script with a tool like Babel (or other) prior to use.

Just say you're working on a large project where you don't control the build process and so you can't integrate your transform scripts with it.

Or alternatively, say you're wanting to run a transform script that comes from somewhere else (eg. another repo checked out somewhere else on the filesystem), and again you can't transparently pre-build the transform.

Current workaround is to make a simple wrapper that does the transform first.

Question is, is it outside the scope of jscodeshift to make it easy to plug-in some preprocessing step for the transform prior to using it? Possible questions:

  • should jscodeshift accept a transform script via standard input? (in which case you could do something like babel myTransform.js | jscodeshift ....)
  • should we expose a --preprocess option that allows the user to specify an executable to pre-process the transform before running it?
  • should we expose another mechanism to inject a JS module that does the preprocessing?
  • what would the implications of this be for preprocessing the other files (ie. the ones that the transform operates on?)

Remove trailing semicolon from ObjectExpression in static ClassProperty

Was looking into how to add a ClassProperty inside of a ClassDeclaration, specifically a static one containing an ObjectExpression. For this, my builder looks similar to:

.replaceWith(
  (p) => j.classBody([
           j.classProperty(
             j.identifier('propTypes'), 
             j.objectExpression(propTypes), 
             null, 
             true
           ),
           ...p.node.body
         ]));

However, a trailing semicolon is added in the transformation, so instead of:

class Foo {
  static foo = {
    bar: 'baz'
  }
}

The transformation looks like:

class Foo {
  static foo = {
    bar: 'baz'
  };
}

Is there any way to exclude this semicolon after the class property definition?

Relevant workspace: http://astexplorer.net/#/5j2WGLMyTF/1

In JSX, some identifiers are processed twice

…or something.

With input

<TAOSchemaDismissableNUX
  context={React.findDOMNode(this.refs.taolinks.refs.delete)}>
</TAOSchemaDismissableNUX>

this script

module.exports = function(file, api) {
  var j = api.jscodeshift;
  console.log(
    j(file.source)
      .find(j.Identifier, {name: 'React'})
      .size()
  );
};

prints 2 which seems wrong.

Create alias for nodePath.replace() to easily remove/delete a node

I frequently finding myself wanting to do:

path.remove();

In order to remove a certain path. Right now I've been doing:

j(path).remove();

In order to remove things. I've recently found out that

path.replace();

also removes a path, can we create an alias to path.replace() at path.remove() ?

Improve finding nodes

We are discussing different ways to improve finding nodes. For now, we'll attempt to build a simple parse API that will allow us to pass a JS pattern into find and uses the existing pattern matching to match things. Let's see how far we take this.

j.find(pattern`var $ = require('merge');`)

// becomes
j.find(j.VariableDeclaration, {
  init: {
    type: 'Identifier',
    name: undefined
  }
});

Alternative approaches would be to use CSS selectors, because they are made to query trees. Another solution would be to extend babylon/acorn but that seems hard to maintain over time.

Problems with output when modifying decorators

Say I have this code:

@Radium
export default class Button extends React.Component {
  render() {}
}

Now, when I'm trying to add another decorator the to list, like so:

return j(file.source)
  .find(j.ExportDefaultDeclaration)
  .filter(p => (decl = p.value.declaration).type === 'ClassDeclaration'
       && decl.superClass.object.name === 'React' && decl.superClass.property.name === 'Component')
  .replaceWith(p => {
      const classDecl = p.value.declaration;
      classDecl.decorators.push(j.decorator(j.identifier('injectStyle')))
      return p.node;
  })
  .toSource();

the output code is being mangled, and the decorators are inserted AFTER the export default bit. Also, the original decorator is still maintained...

@Radium
export default @Radium
@injectStyle
class Button extends React.Component {
  render() {}
}

Transition to using Babel 6

Just wanted to say I love this project! Thank you so much to all the contributor's for their work on this.

After getting used to using jscodeshift inside of http://astexplorer.net, one of the problems I ran into when going to use this on my own machine was the absence of support for Babel 6. Was just curious if there were any plans for supporting Babel 6 in the near future, or if any kind of work has been done already on this front.

Per File Timeout

It would be really useful to have a per-file timeout option. Currently I'm transforming a large number of files, and some individual files are causing my transform to hang (seemingly indefinitely). If I could set a timeout on a per-file basis then I could just continue on and transform all other files.

This could work by killing any process which does not produce any output for a sufficiently long time, then putting whatever jobs it had pending into a new process.

How can I traverse the AST in a depth-first-search type way?

For example I would like to traverse the AST and be able to tell that the second call to undeclaredCall is on an undefined variable. Right now I iterate over the entire tree and would see that undeclaredCall is defined within a functions' parameters and treat it as "declared" throughout the entire file.

function foo(undeclaredCall) {
  undeclaredCall();
}
undeclaredCall();

If I'm able to traverse the AST via a DFS with hooks when I enter and exit different scopes, then I can remove undeclaredCall from the list of declared variables when I leave the scope of foo.

Programmatic Usage

The CLI works great, but it'd be nice to have a friendly API for using jscodeshift within a node script (I'm attempting to use it within yeoman).

Runner.run works, but there's no callback, stream, or promise returned so you can't tell when it's finished. Maybe that's all that needs to be changed.

Console output from transforms is silently swallowed

I'm trying to run transformations but having a really hard time because all my files get skipped and I have no indication of why.

Each of the transformation files use console.log() to tell the user why files were skipped, but for whatever reason, the console.log() statements never make it into stdout.

Question: examples directory

Hi,

I have been reviewing this awesome project and I think it would be cool if the repo had an examples directory where novices (like me) could review some possible transformers. So far the only examples I have seen are at http://astexplorer.net/ and https://medium.com/@cpojer/effective-javascript-codemods-5a6686bb46fb. Conceptually, there are not many projects like this so maybe a bunch of examples showing the potential of the transformers would ease the learning curve.

Would you accept PRs with examples or you prefer to leave them outside this repository? If affirmative, which structure would you prefer?

Cheers

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.