Codemods: add support for codemod debugging

[jsnajdr]

I wanted to debug a codemod script today and found it's not easy. Node needs to be run with --inspect and --debug-brk parameters. That spawns a debugger server and breaks on first statement. jscodeshift must be prevented from spawning worker processes by running it with --run-in-band option. Otherwise, the transform will run in a process different from the one we are debugging.

This PR adds a --debugger option to the run script.

How to test:

1. Run npm run codemod -- --debugger transform-name target-name
2. Open the chrome-devtools:// link you see in terminal in Chrome
3. Enjoy the Chrome debugger paused on the first statement -- set breakpoints, put debugger statements in your code... and run.

I don't know how Node debugging works in editors like VS Code. Maybe @blowery could help with making the debugging work in these?

Some links where I found valuable advice:

• https://medium.com/@paul_irish/debugging-node-js-nightlies-with-chrome-devtools-7c4a1b95ae27
• No instructions on debugging scripts facebook/jscodeshift#223

[matticbot]

Test live: https://calypso.live/?branch=codemod/support-debugging

[simison]

Awesome! Looking forward to use this. :-)

I tested this with Node.js 6.1.5 and Node 8.7.0 (because #19317).

Works great on Node 6, just like you described. Also remains working without the debug param.

On Node 8 this works fine too, I just get a deprecation warning:

$ node --version
v8.7.0

$ npm run codemod -- --debugger single-tree-rendering ./client

> wp-calypso@0.17.0 codemod /####/wp-calypso
> node bin/codemods/run "--debugger" "single-tree-rendering" "./client"


Running single-tree-rendering on ./client
Debugger listening on ws://127.0.0.1:9229/cabe5ade-e762-4944-a41f-96de1cefbd5e
For help see https://nodejs.org/en/docs/inspector
Debugger attached.
(node:19971) [DEP0062] DeprecationWarning: `node --inspect --debug-brk` is deprecated. Please use `node --inspect-brk` instead.

[simison]

As a sidenote, I looked into adding support for jscodeshift's --ignore-pattern, but found it a bit complicated with current setup. Adding something like yargs as a parser would probably simplify this if we want to add any other features later on, but I don't think it's worth adding in just yet. It's also nice not to have one more dependency. :-)

[sirreal]

Very nice, and thanks for the documentation 😀

I left a few documentation suggestions mostly for simplicity and brevity. It's to you whether you want to make any of the changes.

[sirreal]

I think for the docs we can omit this and just include a canonical npm run codemod …. The savvy can figure out the direct invocation if they're interested.

[sirreal]

It sounds like we may be changing the node args soon. How about leaving off the specifics:

This will run jscodeshift in a Node process with the appropriate flags for debugging. The process will break on the first debugger statement, allowing inspection with Chrome.

[sirreal]

If we decide to update the other parts, we might go for a higher level description here as well:

The codemod will be run in a single process to ensure that the debugger is captured, as opposed to normal invocation which spawns worker processes.

[jsnajdr]

Hello @sirreal! i updated the documentation according to your suggestions. I keep mentioning the low-level command line args, but deemphasized into a parenthesized remark.

I also updated the cmdline args to Node 8.

Please have one last look at the changes before I merge them.

[sirreal]

Nice, I just tested on with node 8.