@putout/engine-runner 12.4.1 → 13.0.0

package/README.md

@@ -13,6 +13,17 @@ npm i @putout/engine-runner
 
 ## Supported Plugin Types
 
+There is a couple plugin types supported by 🐊`Putout`:
+
+- ✅[`Replacer`](#replacer)
+- ✅[`Includer`](#includer)
+- ✅[`Traverser`](#traverser)
+- ✅[`Finder`](#finder)
+
+All of them supports subset of `JavaScript` 🦎[`PutoutScript`](https://github.com/coderaiser/putout/blob/master/docs/putout-script.md#-putoutscript) described in [@putout/compare](https://github.com/coderaiser/putout/tree/master/packages/compare#readme).
+
+They goes from simplest to hardest. Let's start from `Replacer`.
+
 ### Replacer
 
 `Replacer` converts code in declarative way. Simplest possible form, no need to use `fix`. Just `from` and `to` parts
@@ -151,7 +162,7 @@ module.exports.filter = (path) => {
 const __ = 'hello';
 ```
 
-Where `__` can be any node. All this possible with help of [@putout/compare](https://github.com/coderaiser/putout/tree/master/packages/compare). Templates format supported in `traverse` and `find` plugins as well.
+Where `__` can be any node. All this possible with help of [@putout/compare](https://github.com/coderaiser/putout/tree/master/packages/compare#readme). Templates format supported in `traverse` and `find` plugins as well.
 
 ### Traverser
 
@@ -171,14 +182,70 @@ module.exports.traverse = ({push}) => ({
 });
 ```
 
-#### Storages
+### Finder
+
+`Find plugins` gives you all the control over traversing, but it's the slowest format.
+Because `traversers` not merged in contrast with other plugin formats.
+
+```js
+module.exports.report = () => 'debugger statement should not be used';
+
+module.exports.fix = (path) => {
+    path.remove();
+};
+
+module.exports.find = (ast, {push, traverse}) => {
+    traverse(ast, {
+        'debugger'(path) {
+            push(path);
+        },
+    });
+};
+```
+
+## Example
+
+```js
+const {runPlugins} = require('@putout/engine-runner');
+const {parse} = require('@putout/engin-parser');
+
+const plugins = [{
+    rule: "remove-debugger",
+    msg: "",        // optional
+    options: {},    // optional
+    plugin: {
+        include: () => ['debugger'],
+        fix: (path) => path.remove(),
+        report: () => `debugger should not be used`,
+    },
+}];
+
+const ast = parse('const m = "hi"; debugger');
+const places = runPlugins({
+    ast,
+    shebang: false,     // default
+    fix: true,          // default
+    fixCount: 1,        // default
+    plugins,
+    parser: 'babel',    // default
+});
+```
+
+## Stores
 
-Storages is preferred way of keeping data 🐊`Putout`, `traverse` init function called only once, and any other way
-of handling variables will most likely will lead to bugs.
+Stores is preferred way of keeping 🐊`Putout` data, `traverse` init function called only once, and any other way
+of handling variables will most likely will lead to bugs. There is 3 store types:
 
-##### listStore
+- ✅`listStore`;
+- ✅`store`;
+- ✅`upstore`;
 
-To keep things and save them as a list during traverse in a safe way `listStore` can be used for code:
+Let's talk about each of them.
+
+### `listStore`
+
+To save things as a list use `listStore`.
+Let's suppose you have such code:
 
 ```js
 debugger;
@@ -187,6 +254,8 @@ debugger;
 const world = '';
 ```
 
+Let's process it!
+
 ```js
 module.exports.traverse = ({listStore}) => ({
     'debugger'(path) {
@@ -205,7 +274,9 @@ module.exports.traverse = ({listStore}) => ({
 });
 ```
 
-When you need `key-value` storage `store` can be used.
+### `store`
+
+When you need `key-value` use `store`:
 
 ```js
 module.exports.traverse = ({push, store}) => ({
@@ -232,9 +303,9 @@ module.exports.traverse = ({push, store}) => ({
 });
 ```
 
-#### Upstore
+### `upstore`
 
-When you need to update already saved values, use `upstore`
+When you need to update already saved values, use `upstore`:
 
 ```js
 module.exports.traverse = ({push, store}) => ({
@@ -269,55 +340,6 @@ module.exports.traverse = ({push, store}) => ({
 });
 ```
 
-### Finder
-
-`Find plugins` gives you all the control over traversing, but it's the slowest format.
-Because `traversers` not merged in contrast with other plugin formats.
-
-```js
-module.exports.report = () => 'debugger statement should not be used';
-
-module.exports.fix = (path) => {
-    path.remove();
-};
-
-module.exports.find = (ast, {push, traverse}) => {
-    traverse(ast, {
-        'debugger'(path) {
-            push(path);
-        },
-    });
-};
-```
-
-## Example
-
-```js
-const {runPlugins} = require('@putout/engine-runner');
-const {parse} = require('@putout/engin-parser');
-
-const plugins = [{
-    rule: "remove-debugger",
-    msg: "",        // optional
-    options: {},    // optional
-    plugin: {
-        include: () => ['debugger'],
-        fix: (path) => path.remove(),
-        report: () => `debugger should not be used`,
-    },
-}];
-
-const ast = parse('const m = "hi"; debugger');
-const places = runPlugins({
-    ast,
-    shebang: false,     // default
-    fix: true,          // default
-    fixCount: 1,        // default
-    plugins,
-    parser: 'babel',    // default
-});
-```
-
 ## Logs
 
 To see logs, use:

package/lib/index.js

@@ -24,9 +24,7 @@ module.exports.runPlugins = ({ast, shebang, fix, fixCount, plugins, template = r
     const {
         pluginsFind,
         pluginsTraverse,
-    } = splitPlugins(plugins, {
-        template,
-    });
+    } = splitPlugins(plugins);
     
     for (let i = 0; i < fixCount; i++) {
         places = run({
@@ -130,7 +128,7 @@ function runWithoutMerge({ast, fix, shebang, template, pluginsFind}) {
     return places;
 }
 
-function splitPlugins(plugins, {template}) {
+function splitPlugins(plugins) {
     const pluginsFind = [];
     const pluginsTraverse = [];
     
@@ -148,9 +146,7 @@ function splitPlugins(plugins, {template}) {
         }
         
         if (plugin.replace) {
-            pluginsTraverse.push(include(replace(item, {
-                template,
-            })));
+            pluginsTraverse.push(include(replace(item)));
             continue;
         }
         

package/lib/replace/index.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const isString = (a) => typeof a === 'string';
+
 const {template} = require('@putout/engine-parser');
 const {
     remove,
@@ -28,13 +30,6 @@ const stubMatch = () => ({});
 const packKeys = (a) => () => keys(a);
 const isObj = (a) => typeof a === 'object';
 
-const validateTemplateValues = (a, b) => {
-    for (const key of keys(a)) {
-        if (!b[key])
-            throw Error(`☝️ Looks like template values not linked: ${stringify(keys(b))} -> ${stringify(keys(a))}`);
-    }
-};
-
 module.exports = ({rule, plugin, msg, options}) => {
     const {
         report,
@@ -124,7 +119,7 @@ const getFix = (items) => (path) => {
 const getFilter = (match = stubMatch, options) => (path) => {
     const all = entries(match({options}));
     
-    for (const [from, fn] of all) {
+    for (const [from, matchProperty] of all) {
         const nodeFrom = template.ast(from);
         
         if (!compare(path.node, nodeFrom)) {
@@ -139,7 +134,9 @@ const getFilter = (match = stubMatch, options) => (path) => {
             node,
         });
         
-        return fn(values, path);
+        validateMatchProperty(matchProperty);
+        
+        return matchProperty(values, path);
     }
     
     return true;
@@ -151,9 +148,24 @@ function parseTo(to, values, path) {
     if (!toStr)
         return null;
     
-    if (isObj(toStr))
+    if (isObj(toStr) && toStr.type)
         return toStr;
     
+    if (!isString(toStr))
+        throw Error(`☝️ Looks like you passed 'replace' value with a wrong type. Allowed: 'string', 'node' and 'path'. Received: '${typeof toStr}' with value '${toStr}'.`);
+    
     return template.ast.fresh(toStr);
 }
 
+function validateMatchProperty(match) {
+    if (!isFn(match))
+        throw Error(`☝️ Looks like 'match' property value is not a 'function', but '${typeof match}' with value '${match}'.`);
+}
+
+const validateTemplateValues = (a, b) => {
+    for (const key of keys(a)) {
+        if (!b[key])
+            throw Error(`☝️ Looks like template values not linked: ${stringify(keys(b))} -> ${stringify(keys(a))}`);
+    }
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putout/engine-runner",
-  "version": "12.4.1",
+  "version": "13.0.0",
   "type": "commonjs",
   "author": "coderaiser <mnemonic.enemy@gmail.com> (https://github.com/coderaiser)",
   "description": "run putout plugins",
@@ -27,7 +27,7 @@
     "@babel/traverse": "^7.12.7",
     "@babel/types": "^7.12.7",
     "@putout/compare": "^8.0.0",
-    "@putout/engine-parser": "^4.0.1",
+    "@putout/engine-parser": "^5.0.0",
     "@putout/operate": "^7.0.0",
     "debug": "^4.1.1",
     "jessy": "^3.0.0",
@@ -46,19 +46,19 @@
     "c8": "^7.5.0",
     "eslint": "^8.0.1",
     "eslint-plugin-node": "^11.0.0",
-    "eslint-plugin-putout": "^13.0.0",
+    "eslint-plugin-putout": "^14.0.0",
     "just-camel-case": "^4.0.2",
     "lerna": "^4.0.0",
-    "madrun": "^8.0.1",
+    "madrun": "^9.0.0",
     "mock-require": "^3.0.3",
     "montag": "^1.0.0",
     "nodemon": "^2.0.1",
     "putout": "*",
-    "supertape": "^6.0.0"
+    "supertape": "^7.0.0"
   },
   "license": "MIT",
   "engines": {
-    "node": ">=14"
+    "node": ">=16"
   },
   "publishConfig": {
     "access": "public"