编写代码以重写代码：jscodeshift

本文概述

• 带有jscodeshift的Codemods
• 什么是jscodeshift？
• 练习1：删除对控制台的调用
• 练习2：替换导入的方法调用
• 练习3：更改方法签名
• 带有jscodeshift概述的Codemods

带有jscodeshift的Codemods

你使用目录中的查找和替换功能对JavaScript源文件进行了几次更改？如果你还不错, 那么你会很喜欢并在捕获组中使用了正则表达式, 因为如果你的代码库相当大, 那么值得付出努力。正则表达式有局限性。对于非平凡的更改, 你需要一个开发人员, 该开发人员应了解上下文中的代码, 并愿意承担冗长, 繁琐且易于出错的过程。

这是” codemods”出现的地方。

Codemod是用于重写其他脚本的脚本。将它们视为可以读写代码的查找和替换功能。你可以使用它们来更新源代码, 以适应团队的编码约定, 在修改API时进行大范围更改, 或者在公共包进行重大更改时甚至自动修复现有代码。

将codemods视为可以读取和写入代码的脚本式查找和替换功能。

鸣叫

在本文中, 我们将探索一个名为” jscodeshift”的代码模块工具包, 同时创建三个复杂性不断提高的代码模块。到最后, 你将广泛了解jscodeshift的重要方面, 并准备开始编写自己的codemod。我们将进行三个练习, 这些练习涵盖了codemods的一些基本但很棒的用法, 你可以在我的github项目上查看这些练习的源代码。

什么是jscodeshift？

jscodeshift工具箱允许你通过转换来泵送一堆源文件, 并用另一端的源文件替换它们。在转换内部, 你将源解析为抽象语法树(AST), 在其中进行更改, 然后从更改后的AST重新生成源。

jscodeshift提供的接口是recast和ast-types包的包装。重铸可处理从源到AST的转换, 而ast-types可处理与AST节点的低级交互。

设定

首先, 从npm全局安装jscodeshift。

npm i -g jscodeshift

你可以使用运行程序选项和经过验证的测试设置, 这些设置使通过Jest(开放源代码JavaScript测试框架)运行一系列测试非常容易, 但是为了简单起见, 我们暂时不进行测试：

jscodeshift -t some-transform.js输入文件.js -d -p

这将通过转换some-transform.js运行input-file.js并在不更改文件的情况下打印结果。

但是, 在进入之前, 重要的是要了解jscodeshift API处理的三种主要对象类型：节点, 节点路径和集合。

节点数

节点是AST的基本组成部分, 通常称为” AST节点”。这些是使用AST Explorer浏览代码时看到的。它们是简单的对象, 不提供任何方法。

节点路径

节点路径是ast类型提供的AST节点周围的包装器, 是遍历抽象语法树(AST, 还记得吗？)的一种方法。孤立地, 节点没有关于其父节点或作用域的任何信息, 因此节点路径会处理这些信息。你可以通过node属性访问包装的节点, 并且有几种方法可以更改基础节点。节点路径通常被称为”路径”。

馆藏

集合是当你查询AST时jscodeshift API返回的零个或多个节点路径的组。它们具有各种有用的方法, 我们将探索其中的一些方法。

集合包含节点路径, 节点路径包含节点, 而节点是AST的组成部分。记住这一点, 将很容易理解jscodeshift查询API。

跟踪这些对象及其各自的API功能之间的差异可能很困难, 因此有一个漂亮的工具jscodeshift-helper可以记录对象类型并提供其他关键信息。

了解节点, 节点路径和集合之间的区别很重要。

练习1：删除对控制台的调用

为了弄清楚我们的脚步, 首先从在代码库中删除对所有控制台方法的调用开始。尽管你可以使用find和replace以及一些正则表达式来做到这一点, 但它在多行语句, 模板文字和更复杂的调用上开始变得棘手, 因此, 这是一个理想的示例。

首先, 创建两个文件, remove-consoles.js和remove-consoles.input.js：

//remove-consoles.js

export default (fileInfo, api) => {
};

//remove-consoles.input.js

export const sum = (a, b) => {
  console.log('calling sum with', arguments);
  return a + b;
};
  
export const multiply = (a, b) => {
  console.warn('calling multiply with', arguments);
  return a * b;
};

export const divide = (a, b) => {
  console.error(`calling divide with ${ arguments }`);
  return a / b;
};

export const average = (a, b) => {
  console.log('calling average with ' + arguments);
  return divide(sum(a, b), 2);
};

这是我们将在终端中使用的将其通过jscodeshift推送的命令：

jscodeshift -t remove-consoles.js remove-consoles.input.js -d -p

如果一切设置正确, 则在运行时, 你应该会看到类似以下的内容。

Processing 1 files... 
Spawning 1 workers...
Running in dry mode, no files will be written! 
Sending 1 files to free worker...
All done. 
Results: 
0 errors
0 unmodified
1 skipped
0 ok
Time elapsed: 0.514seconds

好的, 这有点古板, 因为我们的转换实际上还没有做任何事情, 但至少我们知道这一切都可行。如果根本无法运行, 请确保已全局安装jscodeshift。如果运行转换的命令不正确, 如果找不到输入文件, 则会显示”错误转换文件……不存在”消息或” TypeError：路径必须是字符串或缓冲区”。如果你胖了一些, 应该很容易发现非常描述性的转换错误。

相关：srcmini的快速​​实用JavaScript备忘单：ES6及更高版本

但是, 在成功完成转换之后, 我们的最终目标是查看此源：

export const sum = (a, b) => {
  return a + b;
};
  
export const multiply = (a, b) => {
  return a * b;
};

export const divide = (a, b) => {
  return a / b;
};

export const average = (a, b) => {
  return divide(sum(a, b), 2);
};

为此, 我们需要将源转换为AST, 找到控制台, 将其删除, 然后将更改后的AST转换回源。第一步和最后一步都很容易, 只是：

remove-consoles.js

export default (fileInfo, api) => {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  return root.toSource();
};

但是, 我们如何找到控制台并将其删除？除非你对Mozilla Parser API有一些特殊的了解, 否则你可能需要一个工具来帮助理解AST的外观。为此, 你可以使用AST资源管理器。将remove-consoles.input.js的内容粘贴到其中, 你将看到AST。即使使用最简单的代码也有很多数据, 因此它有助于隐藏位置数据和方法。你可以使用树上方的复选框切换AST Explorer中属性的可见性。

我们可以看到对控制台方法的调用称为CallExpressions, 那么如何在转换中找到它们？我们使用jscodeshift的查询, 还记得我们之前关于Collection, 节点路径和节点本身之间的区别的讨论：

//remove-consoles.js

export default (fileInfo, api) => {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  return root.toSource();
};

行const root = j(fileInfo.source);返回一个节点路径的集合, 该路径包装了AST根节点。我们可以使用集合的find方法来搜索某种类型的后代节点, 如下所示：

const callExpressions = root.find(j.CallExpression);

这将返回另一个仅包含CallExpressions节点的节点路径集合。乍一看, 这似乎是我们想要的, 但是它太宽泛了。我们可能最终通过转换运行了数百或数千个文件, 因此我们必须非常精确, 以确保它可以按预期运行。上面朴素的查找不仅会找到控制台CallExpressions, 还会找到源代码中的每个CallExpression, 包括

require('foo')
bar()
setTimeout(() => {}, 0)

为了提高特异性, 我们为.find提供了第二个参数：一个带有附加参数的对象, 每个节点都需要包含在结果中。我们可以查看AST资源管理器以查看我们的控制台。*调用的形式为：

{
  "type": "CallExpression", "callee": {
    "type": "MemberExpression", "object": {
      "type": "Identifier", "name": "console"
    }
  }
}

有了这些知识, 我们知道可以使用说明符优化查询, 该说明符将仅返回我们感兴趣的CallExpressions类型：

const callExpressions = root.find(j.CallExpression, {
  callee: {
    type: 'MemberExpression', object: { type: 'Identifier', name: 'console' }, }, });

现在我们已经准确地收集了呼叫站点, 让我们将其从AST中删除。方便地, 收集对象类型具有一个remove方法, 即可完成此操作。现在, 我们的remove-consoles.js文件将如下所示：

//remove-consoles.js

export default (fileInfo, api) => {
  const j = api.jscodeshift;

  const root = j(fileInfo.source)

  const callExpressions = root.find(j.CallExpression, {
      callee: {
        type: 'MemberExpression', object: { type: 'Identifier', name: 'console' }, }, }
  );

  callExpressions.remove();

  return root.toSource();
};

现在, 如果我们使用jscodeshift -t remove-consoles.js remove-consoles.input.js -d -p从命令行运行转换, 我们应该看到：

Processing 1 files... 
Spawning 1 workers...
Running in dry mode, no files will be written! 
Sending 1 files to free worker...

export const sum = (a, b) => {
  return a + b;
};
  
export const multiply = (a, b) => {
  return a * b;
};

export const divide = (a, b) => {
  return a / b;
};

export const average = (a, b) => {
  return divide(sum(a, b), 2);
};

All done. 
Results: 
0 errors
0 unmodified
0 skipped
1 ok
Time elapsed: 0.604seconds

这看起来不错的样子。现在, 我们的变换更改了基础的AST, 使用.toSource()生成的字符串与原始字符串不同。我们命令的-p选项显示结果, 底部显示每个处理过的文件的处理结果。从命令中删除-d选项, 将用转换输出替换remove-consoles.input.js的内容。

我们的第一个练习已完成…差不多了。该代码看起来很古怪, 并且可能对那里的任何功能纯粹主义者都非常反感, 因此为了使转换代码更好地流动, jscodeshift使大多数东西都可以链接。这使我们可以像这样重写转换：

// remove-consoles.js

export default (fileInfo, api) => {
  const j = api.jscodeshift;

  return j(fileInfo.source)
    .find(j.CallExpression, {
        callee: {
          type: 'MemberExpression', object: { type: 'Identifier', name: 'console' }, }, }
    )
    .remove()
    .toSource();
};

好多了。回顾练习1, 我们包装了源, 查询了节点路径的集合, 更改了AST, 然后重新生成了该源。我们举了一个非常简单的例子, 弄清了最重要的方面。现在, 让我们做一些更有趣的事情。

练习2：替换导入的方法调用

对于这种情况, 我们使用了名为” circleArea”的方法的” geometry”模块, 我们已弃用了” getCircleArea”。我们可以轻松找到并替换为/geometry\.circleArea/g, 但是如果用户导入了模块并为其指定了其他名称该怎么办？例如：

import g from 'geometry';
const area = g.circleArea(radius);

我们怎么知道要替换g.circleArea而不是geometry.circleArea？我们当然不能假定所有circleArea调用都是我们要找的, 我们需要一些上下文。这是codemods开始显示其值的地方。首先制作两个文件deprecated.js和deprecated.input.js。

//deprecated.js

export default (fileInfo, api) => {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  return root.toSource();
};

deprecated.input.js

import g from 'geometry';
import otherModule from 'otherModule';

const radius = 20;
const area = g.circleArea(radius);

console.log(area === Math.pow(g.getPi(), 2) * radius);
console.log(area === otherModule.circleArea(radius));

现在运行此命令以运行codemod。

jscodeshift -t ./deprecated.js ./deprecated.input.js -d -p

你应该看到输出指示转换已运行, 但尚未进行任何更改。

Processing 1 files... 
Spawning 1 workers...
Running in dry mode, no files will be written! 
Sending 1 files to free worker...
All done. 
Results: 
0 errors
1 unmodified
0 skipped
0 ok
Time elapsed: 0.892seconds

我们需要知道什么导入了几何模块。让我们看一下AST浏览器, 找出我们要寻找的东西。我们的进口采用这种形式。

{
  "type": "ImportDeclaration", "specifiers": [
    {
      "type": "ImportDefaultSpecifier", "local": {
        "type": "Identifier", "name": "g"
      }
    }
  ], "source": {
    "type": "Literal", "value": "geometry"
  }
}

我们可以指定一个对象类型来查找这样的节点集合：

const importDeclaration = root.find(j.ImportDeclaration, {
    source: {
      type: 'Literal', value: 'geometry', }, });

这使我们获得了用于导入”几何图形”的ImportDeclaration。从那里开始, 找到用于保存导入模块的本地名称。由于这是我们第一次这样做, 因此在开始时要指出一个重要且令人困惑的观点。

注意：重要的是要知道root.find()返回节点路径的集合。从那里, .get(n)方法返回该集合中索引n处的节点路径, 并使用.node来获取实际节点。该节点基本上就是我们在AST Explorer中看到的。请记住, 节点路径主要是有关节点范围和关系的信息, 而不是节点本身。

// find the Identifiers
const identifierCollection = importDeclaration.find(j.Identifier);

// get the first NodePath from the Collection
const nodePath = identifierCollection.get(0);

// get the Node in the NodePath and grab its "name"
const localName = nodePath.node.name;

这使我们可以动态地找出已导入几何模块的内容。接下来, 我们找到它的使用位置并进行更改。通过查看AST Explorer, 我们可以发现我们需要找到如下所示的MemberExpression：

{
  "type": "MemberExpression", "object": {
    "name": "geometry"
  }, "property": {
    "name": "circleArea"
  }
}

但是请记住, 我们的模块可能是用不同的名称导入的, 因此我们必须通过使查询看起来像这样来解决这个问题：

j.MemberExpression, {
  object: {
    name: localName, }, property: {
    name: "circleArea", }, })

现在, 有了查询, 我们可以将所有调用站点的集合收集到旧方法中, 然后使用该集合的replaceWith()方法将其替换掉。 replaceWith()方法遍历集合, 将每个节点路径传递给回调函数。然后将AST节点替换为你从回调返回的任何节点。

再次, 了解集合, 节点路径和节点之间的区别对于使之有意义是必要的。

替换完成后, 我们将照常生成源。这是我们完成的转换：

//deprecated.js
export default (fileInfo, api) => {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  // find declaration for "geometry" import
  const importDeclaration = root.find(j.ImportDeclaration, {
    source: {
      type: 'Literal', value: 'geometry', }, });

  // get the local name for the imported module
  const localName =
    // find the Identifiers
    importDeclaration.find(j.Identifier)
    // get the first NodePath from the Collection
    .get(0)
    // get the Node in the NodePath and grab its "name"
    .node.name;

  return root.find(j.MemberExpression, {
      object: {
        name: localName, }, property: {
        name: 'circleArea', }, })

    .replaceWith(nodePath => {
      // get the underlying Node
      const { node } = nodePath;
      // change to our new prop
      node.property.name = 'getCircleArea';
      // replaceWith should return a Node, not a NodePath
      return node;
    })

    .toSource();
};

当通过转换运行源代码时, 我们看到在geometry模块中对不赞成使用的方法的调用已更改, 但其余部分保持不变, 如下所示：

import g from 'geometry';
import otherModule from 'otherModule';

const radius = 20;
const area = g.getCircleArea(radius);

console.log(area === Math.pow(g.getPi(), 2) * radius);
console.log(area === otherModule.circleArea(radius));

练习3：更改方法签名

在之前的练习中, 我们介绍了查询集合以查找特定类型的节点, 删除节点和更改节点, 但是如何创建新的节点呢？这就是我们在本练习中要解决的问题。

在这种情况下, 随着软件的不断发展, 我们已经失去了对方法参数的控制权, 而且各个参数也无法控制, 因此可以决定接受一个包含这些参数的对象会更好。

而不是car.factory(‘white’, ‘Kia’, ‘Sorento’, 2010, 50000, null, true);

我们想看看

const suv = car.factory({
  color: 'white', make: 'Kia', model: 'Sorento', year: 2010, miles: 50000, bedliner: null, alarm: true, });

首先, 进行转换和输入文件以进行测试：

//signature-change.js

export default (fileInfo, api) => {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  return root.toSource();
};

//signature-change.input.js

import car from 'car';

const suv = car.factory('white', 'Kia', 'Sorento', 2010, 50000, null, true);
const truck = car.factory('silver', 'Toyota', 'Tacoma', 2006, 100000, true, true);

我们运行转换的命令是jscodeshift -t signature-change.js signature-change.input.js -d -p, 执行此转换所需的步骤为：

• 查找导入模块的本地名称
• 找到所有呼叫站点到.factory方法
• 阅读所有传入的参数
• 用单个参数替换该调用, 该参数包含具有原始值的对象

使用AST Explorer和我们在前面的练习中使用的过程, 前两个步骤很容易：

//signature-change.js

export default (fileInfo, api) => {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  // find declaration for "car" import
  const importDeclaration = root.find(j.ImportDeclaration, {
    source: {
      type: 'Literal', value: 'car', }, });

  // get the local name for the imported module
  const localName =
    importDeclaration.find(j.Identifier)
    .get(0)
    .node.name;

  // find where `.factory` is being called
  return root.find(j.CallExpression, {
      callee: {
        type: 'MemberExpression', object: {
          name: localName, }, property: {
          name: 'factory', }, }
    })
    .toSource();
};

为了读取当前传递的所有参数, 我们在CallExpressions集合上使用thereplaceWith()方法来交换每个节点。新节点将用新的单个参数(对象)替换node.arguments。

用’replacewith()’更改方法签名并换出整个节点。

让我们尝试一个简单的对象, 以确保在使用适当的值之前我们知道它是如何工作的：

    .replaceWith(nodePath => {
      const { node } = nodePath;
      node.arguments = [{ foo: 'bar' }];
      return node;
    })

当我们运行此代码(jscodeshift -t signature-change.js signature-change.input.js -d -p)时, 转换将爆炸：

 ERR signature-change.input.js Transformation error
Error: {foo: bar} does not match type Printable

事实证明, 我们不能只是将普通对象塞入AST节点。相反, 我们需要使用构建器来创建适当的节点。

相关：雇用3％的自由JavaScript开发人员。

节点构建器

构建器使我们能够正确创建新节点；它们由ast-types提供, 并通过jscodeshift浮出水面。他们严格检查是否正确创建了不同类型的节点, 当你一劳永逸地投入工作时, 这可能会令人沮丧, 但是最终, 这是一件好事。要了解如何使用构建器, 应牢记两件事：

所有可用的AST节点类型都在ast-types github项目的deffolder中定义, 主要是在core.js中定义。所有AST节点类型都有构建器, 但是它们使用驼峰式版本的节点类型, 而不是pascal-案件。 (没有明确说明, 但是你可以在ast-types源中看到这种情况

如果我们使用AST Explorer并举例说明我们希望得到的结果, 则可以很容易地将其组合在一起。在我们的例子中, 我们希望新的单个参数是具有一堆属性的ObjectExpression。查看上面提到的类型定义, 我们可以看到其中的含义：

def("ObjectExpression")
    .bases("Expression")
    .build("properties")
    .field("properties", [def("Property")]);

def("Property")
    .bases("Node")
    .build("kind", "key", "value")
    .field("kind", or("init", "get", "set"))
    .field("key", or(def("Literal"), def("Identifier")))
    .field("value", def("Expression"));

因此, 为{foo：’bar’}构建AST节点的代码如下所示：

j.objectExpression([
  j.property(
    'init', j.identifier('foo'), j.literal('bar')
  )  
]);

取得该代码并将其插入我们的转换中, 如下所示：

.replaceWith(nodePath => {
      const { node } = nodePath;
      const object = j.objectExpression([
        j.property(
          'init', j.identifier('foo'), j.literal('bar')
        )
      ]);
      node.arguments = [object];
      return node;
    })

运行此命令可获得结果：

import car from 'car';

const suv = car.factory({
  foo: "bar"
});
const truck = car.factory({
  foo: "bar"
});

现在, 我们知道了如何创建合适的AST节点, 现在很容易遍历旧的参数并生成一个新的对象来使用。这是我们的signature-change.js文件现在的样子：

//signature-change.js

export default (fileInfo, api) => {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  // find declaration for "car" import
  const importDeclaration = root.find(j.ImportDeclaration, {
    source: {
      type: 'Literal', value: 'car', }, });

  // get the local name for the imported module
  const localName =
    importDeclaration.find(j.Identifier)
    .get(0)
    .node.name;

  // current order of arguments
  const argKeys = [
    'color', 'make', 'model', 'year', 'miles', 'bedliner', 'alarm', ];

  // find where `.factory` is being called
  return root.find(j.CallExpression, {
      callee: {
        type: 'MemberExpression', object: {
          name: localName, }, property: {
          name: 'factory', }, }
    })
    .replaceWith(nodePath => {
      const { node } = nodePath;

      // use a builder to create the ObjectExpression
      const argumentsAsObject = j.objectExpression(

        // map the arguments to an Array of Property Nodes
        node.arguments.map((arg, i) =>
          j.property(
            'init', j.identifier(argKeys[i]), j.literal(arg.value)
          )
        )
      );

      // replace the arguments with our new ObjectExpression
      node.arguments = [argumentsAsObject];

      return node;
    })

    // specify print options for recast
    .toSource({ quote: 'single', trailingComma: true });
};

运行转换(jscodeshift -t signature-change.js signature-change.input.js -d -p), 我们将看到签名已按预期更新：

import car from 'car';

const suv = car.factory({
  color: 'white', make: 'Kia', model: 'Sorento', year: 2010, miles: 50000, bedliner: null, alarm: true, });
const truck = car.factory({
  color: 'silver', make: 'Toyota', model: 'Tacoma', year: 2006, miles: 100000, bedliner: true, alarm: true, });

带有jscodeshift概述的Codemods

要花费一点时间和精力才能达到这一点, 但是面对大规模重构时, 好处是巨大的。 jscodeshift擅长将文件组分配给不同的进程并并行运行它们, 从而使你可以在几秒钟内跨庞大的代码库运行复杂的转换。随着你对Codemod的熟练掌握, 你将开始重新利用现有脚本(例如react-codemod github存储库或为各种任务编写自己的脚本), 这将使你, 你的团队和你的包用户更加高效。