eslint/lib/linter/code-path-analysis/debug-helpers.js

   1 /**
   2  * @fileoverview Helpers to debug for code path analysis.
   3  * @author Toru Nagashima
   4  */
   5
   6 "use strict";
   7
   8 //------------------------------------------------------------------------------
   9 // Requirements
  10 //------------------------------------------------------------------------------
  11
  12 const debug = require("debug")("eslint:code-path");
  13
  14 //------------------------------------------------------------------------------
  15 // Helpers
  16 //------------------------------------------------------------------------------
  17
  18 /**
  19  * Gets id of a given segment.
  20  * @param {CodePathSegment} segment A segment to get.
  21  * @returns {string} Id of the segment.
  22  */
  23 /* istanbul ignore next */
  24 function getId(segment) { // eslint-disable-line jsdoc/require-jsdoc
  25     return segment.id + (segment.reachable ? "" : "!");
  26 }
  27
  28 //------------------------------------------------------------------------------
  29 // Public Interface
  30 //------------------------------------------------------------------------------
  31
  32 module.exports = {
  33
  34     /**
  35      * A flag that debug dumping is enabled or not.
  36      * @type {boolean}
  37      */
  38     enabled: debug.enabled,
  39
  40     /**
  41      * Dumps given objects.
  42      * @param {...any} args objects to dump.
  43      * @returns {void}
  44      */
  45     dump: debug,
  46
  47     /**
  48      * Dumps the current analyzing state.
  49      * @param {ASTNode} node A node to dump.
  50      * @param {CodePathState} state A state to dump.
  51      * @param {boolean} leaving A flag whether or not it's leaving
  52      * @returns {void}
  53      */
  54     dumpState: !debug.enabled ? debug : /* istanbul ignore next */ function(node, state, leaving) {
  55         for (let i = 0; i < state.currentSegments.length; ++i) {
  56             const segInternal = state.currentSegments[i].internal;
  57
  58             if (leaving) {
  59                 segInternal.exitNodes.push(node);
  60             } else {
  61                 segInternal.nodes.push(node);
  62             }
  63         }
  64
  65         debug([
  66             `${state.currentSegments.map(getId).join(",")})`,
  67             `${node.type}${leaving ? ":exit" : ""}`
  68         ].join(" "));
  69     },
  70
  71     /**
  72      * Dumps a DOT code of a given code path.
  73      * The DOT code can be visualized with Graphvis.
  74      * @param {CodePath} codePath A code path to dump.
  75      * @returns {void}
  76      * @see http://www.graphviz.org
  77      * @see http://www.webgraphviz.com
  78      */
  79     dumpDot: !debug.enabled ? debug : /* istanbul ignore next */ function(codePath) {
  80         let text =
  81             "\n" +
  82             "digraph {\n" +
  83             "node[shape=box,style=\"rounded,filled\",fillcolor=white];\n" +
  84             "initial[label=\"\",shape=circle,style=filled,fillcolor=black,width=0.25,height=0.25];\n";
  85
  86         if (codePath.returnedSegments.length > 0) {
  87             text += "final[label=\"\",shape=doublecircle,style=filled,fillcolor=black,width=0.25,height=0.25];\n";
  88         }
  89         if (codePath.thrownSegments.length > 0) {
  90             text += "thrown[label=\"✘\",shape=circle,width=0.3,height=0.3,fixedsize];\n";
  91         }
  92
  93         const traceMap = Object.create(null);
  94         const arrows = this.makeDotArrows(codePath, traceMap);
  95
  96         for (const id in traceMap) { // eslint-disable-line guard-for-in
  97             const segment = traceMap[id];
  98
  99             text += `${id}[`;
 100
 101             if (segment.reachable) {
 102                 text += "label=\"";
 103             } else {
 104                 text += "style=\"rounded,dashed,filled\",fillcolor=\"#FF9800\",label=\"<<unreachable>>\\n";
 105             }
 106
 107             if (segment.internal.nodes.length > 0 || segment.internal.exitNodes.length > 0) {
 108                 text += [].concat(
 109                     segment.internal.nodes.map(node => {
 110                         switch (node.type) {
 111                             case "Identifier": return `${node.type} (${node.name})`;
 112                             case "Literal": return `${node.type} (${node.value})`;
 113                             default: return node.type;
 114                         }
 115                     }),
 116                     segment.internal.exitNodes.map(node => {
 117                         switch (node.type) {
 118                             case "Identifier": return `${node.type}:exit (${node.name})`;
 119                             case "Literal": return `${node.type}:exit (${node.value})`;
 120                             default: return `${node.type}:exit`;
 121                         }
 122                     })
 123                 ).join("\\n");
 124             } else {
 125                 text += "????";
 126             }
 127
 128             text += "\"];\n";
 129         }
 130
 131         text += `${arrows}\n`;
 132         text += "}";
 133         debug("DOT", text);
 134     },
 135
 136     /**
 137      * Makes a DOT code of a given code path.
 138      * The DOT code can be visualized with Graphvis.
 139      * @param {CodePath} codePath A code path to make DOT.
 140      * @param {Object} traceMap Optional. A map to check whether or not segments had been done.
 141      * @returns {string} A DOT code of the code path.
 142      */
 143     makeDotArrows(codePath, traceMap) {
 144         const stack = [[codePath.initialSegment, 0]];
 145         const done = traceMap || Object.create(null);
 146         let lastId = codePath.initialSegment.id;
 147         let text = `initial->${codePath.initialSegment.id}`;
 148
 149         while (stack.length > 0) {
 150             const item = stack.pop();
 151             const segment = item[0];
 152             const index = item[1];
 153
 154             if (done[segment.id] && index === 0) {
 155                 continue;
 156             }
 157             done[segment.id] = segment;
 158
 159             const nextSegment = segment.allNextSegments[index];
 160
 161             if (!nextSegment) {
 162                 continue;
 163             }
 164
 165             if (lastId === segment.id) {
 166                 text += `->${nextSegment.id}`;
 167             } else {
 168                 text += `;\n${segment.id}->${nextSegment.id}`;
 169             }
 170             lastId = nextSegment.id;
 171
 172             stack.unshift([segment, 1 + index]);
 173             stack.push([nextSegment, 0]);
 174         }
 175
 176         codePath.returnedSegments.forEach(finalSegment => {
 177             if (lastId === finalSegment.id) {
 178                 text += "->final";
 179             } else {
 180                 text += `;\n${finalSegment.id}->final`;
 181             }
 182             lastId = null;
 183         });
 184
 185         codePath.thrownSegments.forEach(finalSegment => {
 186             if (lastId === finalSegment.id) {
 187                 text += "->thrown";
 188             } else {
 189                 text += `;\n${finalSegment.id}->thrown`;
 190             }
 191             lastId = null;
 192         });
 193
 194         return `${text};`;
 195     }
 196 };