eslint/lib/rules/key-spacing.js

   1 /**
   2  * @fileoverview Rule to specify spacing of object literal keys and values
   3  * @author Brandon Mills
   4  */
   5 "use strict";
   6
   7 //------------------------------------------------------------------------------
   8 // Requirements
   9 //------------------------------------------------------------------------------
  10
  11 const astUtils = require("./utils/ast-utils");
  12
  13 //------------------------------------------------------------------------------
  14 // Helpers
  15 //------------------------------------------------------------------------------
  16
  17 /**
  18  * Checks whether a string contains a line terminator as defined in
  19  * http://www.ecma-international.org/ecma-262/5.1/#sec-7.3
  20  * @param {string} str String to test.
  21  * @returns {boolean} True if str contains a line terminator.
  22  */
  23 function containsLineTerminator(str) {
  24     return astUtils.LINEBREAK_MATCHER.test(str);
  25 }
  26
  27 /**
  28  * Gets the last element of an array.
  29  * @param {Array} arr An array.
  30  * @returns {any} Last element of arr.
  31  */
  32 function last(arr) {
  33     return arr[arr.length - 1];
  34 }
  35
  36 /**
  37  * Checks whether a node is contained on a single line.
  38  * @param {ASTNode} node AST Node being evaluated.
  39  * @returns {boolean} True if the node is a single line.
  40  */
  41 function isSingleLine(node) {
  42     return (node.loc.end.line === node.loc.start.line);
  43 }
  44
  45 /**
  46  * Checks whether the properties on a single line.
  47  * @param {ASTNode[]} properties List of Property AST nodes.
  48  * @returns {boolean} True if all properties is on a single line.
  49  */
  50 function isSingleLineProperties(properties) {
  51     const [firstProp] = properties,
  52         lastProp = last(properties);
  53
  54     return firstProp.loc.start.line === lastProp.loc.end.line;
  55 }
  56
  57 /**
  58  * Initializes a single option property from the configuration with defaults for undefined values
  59  * @param {Object} toOptions Object to be initialized
  60  * @param {Object} fromOptions Object to be initialized from
  61  * @returns {Object} The object with correctly initialized options and values
  62  */
  63 function initOptionProperty(toOptions, fromOptions) {
  64     toOptions.mode = fromOptions.mode || "strict";
  65
  66     // Set value of beforeColon
  67     if (typeof fromOptions.beforeColon !== "undefined") {
  68         toOptions.beforeColon = +fromOptions.beforeColon;
  69     } else {
  70         toOptions.beforeColon = 0;
  71     }
  72
  73     // Set value of afterColon
  74     if (typeof fromOptions.afterColon !== "undefined") {
  75         toOptions.afterColon = +fromOptions.afterColon;
  76     } else {
  77         toOptions.afterColon = 1;
  78     }
  79
  80     // Set align if exists
  81     if (typeof fromOptions.align !== "undefined") {
  82         if (typeof fromOptions.align === "object") {
  83             toOptions.align = fromOptions.align;
  84         } else { // "string"
  85             toOptions.align = {
  86                 on: fromOptions.align,
  87                 mode: toOptions.mode,
  88                 beforeColon: toOptions.beforeColon,
  89                 afterColon: toOptions.afterColon
  90             };
  91         }
  92     }
  93
  94     return toOptions;
  95 }
  96
  97 /**
  98  * Initializes all the option values (singleLine, multiLine and align) from the configuration with defaults for undefined values
  99  * @param {Object} toOptions Object to be initialized
 100  * @param {Object} fromOptions Object to be initialized from
 101  * @returns {Object} The object with correctly initialized options and values
 102  */
 103 function initOptions(toOptions, fromOptions) {
 104     if (typeof fromOptions.align === "object") {
 105
 106         // Initialize the alignment configuration
 107         toOptions.align = initOptionProperty({}, fromOptions.align);
 108         toOptions.align.on = fromOptions.align.on || "colon";
 109         toOptions.align.mode = fromOptions.align.mode || "strict";
 110
 111         toOptions.multiLine = initOptionProperty({}, (fromOptions.multiLine || fromOptions));
 112         toOptions.singleLine = initOptionProperty({}, (fromOptions.singleLine || fromOptions));
 113
 114     } else { // string or undefined
 115         toOptions.multiLine = initOptionProperty({}, (fromOptions.multiLine || fromOptions));
 116         toOptions.singleLine = initOptionProperty({}, (fromOptions.singleLine || fromOptions));
 117
 118         // If alignment options are defined in multiLine, pull them out into the general align configuration
 119         if (toOptions.multiLine.align) {
 120             toOptions.align = {
 121                 on: toOptions.multiLine.align.on,
 122                 mode: toOptions.multiLine.align.mode || toOptions.multiLine.mode,
 123                 beforeColon: toOptions.multiLine.align.beforeColon,
 124                 afterColon: toOptions.multiLine.align.afterColon
 125             };
 126         }
 127     }
 128
 129     return toOptions;
 130 }
 131
 132 //------------------------------------------------------------------------------
 133 // Rule Definition
 134 //------------------------------------------------------------------------------
 135
 136 module.exports = {
 137     meta: {
 138         type: "layout",
 139
 140         docs: {
 141             description: "enforce consistent spacing between keys and values in object literal properties",
 142             recommended: false,
 143             url: "https://eslint.org/docs/rules/key-spacing"
 144         },
 145
 146         fixable: "whitespace",
 147
 148         schema: [{
 149             anyOf: [
 150                 {
 151                     type: "object",
 152                     properties: {
 153                         align: {
 154                             anyOf: [
 155                                 {
 156                                     enum: ["colon", "value"]
 157                                 },
 158                                 {
 159                                     type: "object",
 160                                     properties: {
 161                                         mode: {
 162                                             enum: ["strict", "minimum"]
 163                                         },
 164                                         on: {
 165                                             enum: ["colon", "value"]
 166                                         },
 167                                         beforeColon: {
 168                                             type: "boolean"
 169                                         },
 170                                         afterColon: {
 171                                             type: "boolean"
 172                                         }
 173                                     },
 174                                     additionalProperties: false
 175                                 }
 176                             ]
 177                         },
 178                         mode: {
 179                             enum: ["strict", "minimum"]
 180                         },
 181                         beforeColon: {
 182                             type: "boolean"
 183                         },
 184                         afterColon: {
 185                             type: "boolean"
 186                         }
 187                     },
 188                     additionalProperties: false
 189                 },
 190                 {
 191                     type: "object",
 192                     properties: {
 193                         singleLine: {
 194                             type: "object",
 195                             properties: {
 196                                 mode: {
 197                                     enum: ["strict", "minimum"]
 198                                 },
 199                                 beforeColon: {
 200                                     type: "boolean"
 201                                 },
 202                                 afterColon: {
 203                                     type: "boolean"
 204                                 }
 205                             },
 206                             additionalProperties: false
 207                         },
 208                         multiLine: {
 209                             type: "object",
 210                             properties: {
 211                                 align: {
 212                                     anyOf: [
 213                                         {
 214                                             enum: ["colon", "value"]
 215                                         },
 216                                         {
 217                                             type: "object",
 218                                             properties: {
 219                                                 mode: {
 220                                                     enum: ["strict", "minimum"]
 221                                                 },
 222                                                 on: {
 223                                                     enum: ["colon", "value"]
 224                                                 },
 225                                                 beforeColon: {
 226                                                     type: "boolean"
 227                                                 },
 228                                                 afterColon: {
 229                                                     type: "boolean"
 230                                                 }
 231                                             },
 232                                             additionalProperties: false
 233                                         }
 234                                     ]
 235                                 },
 236                                 mode: {
 237                                     enum: ["strict", "minimum"]
 238                                 },
 239                                 beforeColon: {
 240                                     type: "boolean"
 241                                 },
 242                                 afterColon: {
 243                                     type: "boolean"
 244                                 }
 245                             },
 246                             additionalProperties: false
 247                         }
 248                     },
 249                     additionalProperties: false
 250                 },
 251                 {
 252                     type: "object",
 253                     properties: {
 254                         singleLine: {
 255                             type: "object",
 256                             properties: {
 257                                 mode: {
 258                                     enum: ["strict", "minimum"]
 259                                 },
 260                                 beforeColon: {
 261                                     type: "boolean"
 262                                 },
 263                                 afterColon: {
 264                                     type: "boolean"
 265                                 }
 266                             },
 267                             additionalProperties: false
 268                         },
 269                         multiLine: {
 270                             type: "object",
 271                             properties: {
 272                                 mode: {
 273                                     enum: ["strict", "minimum"]
 274                                 },
 275                                 beforeColon: {
 276                                     type: "boolean"
 277                                 },
 278                                 afterColon: {
 279                                     type: "boolean"
 280                                 }
 281                             },
 282                             additionalProperties: false
 283                         },
 284                         align: {
 285                             type: "object",
 286                             properties: {
 287                                 mode: {
 288                                     enum: ["strict", "minimum"]
 289                                 },
 290                                 on: {
 291                                     enum: ["colon", "value"]
 292                                 },
 293                                 beforeColon: {
 294                                     type: "boolean"
 295                                 },
 296                                 afterColon: {
 297                                     type: "boolean"
 298                                 }
 299                             },
 300                             additionalProperties: false
 301                         }
 302                     },
 303                     additionalProperties: false
 304                 }
 305             ]
 306         }],
 307         messages: {
 308             extraKey: "Extra space after {{computed}}key '{{key}}'.",
 309             extraValue: "Extra space before value for {{computed}}key '{{key}}'.",
 310             missingKey: "Missing space after {{computed}}key '{{key}}'.",
 311             missingValue: "Missing space before value for {{computed}}key '{{key}}'."
 312         }
 313     },
 314
 315     create(context) {
 316
 317         /**
 318          * OPTIONS
 319          * "key-spacing": [2, {
 320          *     beforeColon: false,
 321          *     afterColon: true,
 322          *     align: "colon" // Optional, or "value"
 323          * }
 324          */
 325         const options = context.options[0] || {},
 326             ruleOptions = initOptions({}, options),
 327             multiLineOptions = ruleOptions.multiLine,
 328             singleLineOptions = ruleOptions.singleLine,
 329             alignmentOptions = ruleOptions.align || null;
 330
 331         const sourceCode = context.getSourceCode();
 332
 333         /**
 334          * Checks whether a property is a member of the property group it follows.
 335          * @param {ASTNode} lastMember The last Property known to be in the group.
 336          * @param {ASTNode} candidate The next Property that might be in the group.
 337          * @returns {boolean} True if the candidate property is part of the group.
 338          */
 339         function continuesPropertyGroup(lastMember, candidate) {
 340             const groupEndLine = lastMember.loc.start.line,
 341                 candidateStartLine = candidate.loc.start.line;
 342
 343             if (candidateStartLine - groupEndLine <= 1) {
 344                 return true;
 345             }
 346
 347             /*
 348              * Check that the first comment is adjacent to the end of the group, the
 349              * last comment is adjacent to the candidate property, and that successive
 350              * comments are adjacent to each other.
 351              */
 352             const leadingComments = sourceCode.getCommentsBefore(candidate);
 353
 354             if (
 355                 leadingComments.length &&
 356                 leadingComments[0].loc.start.line - groupEndLine <= 1 &&
 357                 candidateStartLine - last(leadingComments).loc.end.line <= 1
 358             ) {
 359                 for (let i = 1; i < leadingComments.length; i++) {
 360                     if (leadingComments[i].loc.start.line - leadingComments[i - 1].loc.end.line > 1) {
 361                         return false;
 362                     }
 363                 }
 364                 return true;
 365             }
 366
 367             return false;
 368         }
 369
 370         /**
 371          * Determines if the given property is key-value property.
 372          * @param {ASTNode} property Property node to check.
 373          * @returns {boolean} Whether the property is a key-value property.
 374          */
 375         function isKeyValueProperty(property) {
 376             return !(
 377                 (property.method ||
 378                 property.shorthand ||
 379                 property.kind !== "init" || property.type !== "Property") // Could be "ExperimentalSpreadProperty" or "SpreadElement"
 380             );
 381         }
 382
 383         /**
 384          * Starting from the given a node (a property.key node here) looks forward
 385          * until it finds the last token before a colon punctuator and returns it.
 386          * @param {ASTNode} node The node to start looking from.
 387          * @returns {ASTNode} The last token before a colon punctuator.
 388          */
 389         function getLastTokenBeforeColon(node) {
 390             const colonToken = sourceCode.getTokenAfter(node, astUtils.isColonToken);
 391
 392             return sourceCode.getTokenBefore(colonToken);
 393         }
 394
 395         /**
 396          * Starting from the given a node (a property.key node here) looks forward
 397          * until it finds the colon punctuator and returns it.
 398          * @param {ASTNode} node The node to start looking from.
 399          * @returns {ASTNode} The colon punctuator.
 400          */
 401         function getNextColon(node) {
 402             return sourceCode.getTokenAfter(node, astUtils.isColonToken);
 403         }
 404
 405         /**
 406          * Gets an object literal property's key as the identifier name or string value.
 407          * @param {ASTNode} property Property node whose key to retrieve.
 408          * @returns {string} The property's key.
 409          */
 410         function getKey(property) {
 411             const key = property.key;
 412
 413             if (property.computed) {
 414                 return sourceCode.getText().slice(key.range[0], key.range[1]);
 415             }
 416             return astUtils.getStaticPropertyName(property);
 417         }
 418
 419         /**
 420          * Reports an appropriately-formatted error if spacing is incorrect on one
 421          * side of the colon.
 422          * @param {ASTNode} property Key-value pair in an object literal.
 423          * @param {string} side Side being verified - either "key" or "value".
 424          * @param {string} whitespace Actual whitespace string.
 425          * @param {int} expected Expected whitespace length.
 426          * @param {string} mode Value of the mode as "strict" or "minimum"
 427          * @returns {void}
 428          */
 429         function report(property, side, whitespace, expected, mode) {
 430             const diff = whitespace.length - expected;
 431
 432             if ((
 433                 diff && mode === "strict" ||
 434                 diff < 0 && mode === "minimum" ||
 435                 diff > 0 && !expected && mode === "minimum") &&
 436                 !(expected && containsLineTerminator(whitespace))
 437             ) {
 438                 const nextColon = getNextColon(property.key),
 439                     tokenBeforeColon = sourceCode.getTokenBefore(nextColon, { includeComments: true }),
 440                     tokenAfterColon = sourceCode.getTokenAfter(nextColon, { includeComments: true }),
 441                     isKeySide = side === "key",
 442                     isExtra = diff > 0,
 443                     diffAbs = Math.abs(diff),
 444                     spaces = Array(diffAbs + 1).join(" ");
 445
 446                 const locStart = isKeySide ? tokenBeforeColon.loc.end : nextColon.loc.start;
 447                 const locEnd = isKeySide ? nextColon.loc.start : tokenAfterColon.loc.start;
 448                 const missingLoc = isKeySide ? tokenBeforeColon.loc : tokenAfterColon.loc;
 449                 const loc = isExtra ? { start: locStart, end: locEnd } : missingLoc;
 450
 451                 let fix;
 452
 453                 if (isExtra) {
 454                     let range;
 455
 456                     // Remove whitespace
 457                     if (isKeySide) {
 458                         range = [tokenBeforeColon.range[1], tokenBeforeColon.range[1] + diffAbs];
 459                     } else {
 460                         range = [tokenAfterColon.range[0] - diffAbs, tokenAfterColon.range[0]];
 461                     }
 462                     fix = function(fixer) {
 463                         return fixer.removeRange(range);
 464                     };
 465                 } else {
 466
 467                     // Add whitespace
 468                     if (isKeySide) {
 469                         fix = function(fixer) {
 470                             return fixer.insertTextAfter(tokenBeforeColon, spaces);
 471                         };
 472                     } else {
 473                         fix = function(fixer) {
 474                             return fixer.insertTextBefore(tokenAfterColon, spaces);
 475                         };
 476                     }
 477                 }
 478
 479                 let messageId = "";
 480
 481                 if (isExtra) {
 482                     messageId = side === "key" ? "extraKey" : "extraValue";
 483                 } else {
 484                     messageId = side === "key" ? "missingKey" : "missingValue";
 485                 }
 486
 487                 context.report({
 488                     node: property[side],
 489                     loc,
 490                     messageId,
 491                     data: {
 492                         computed: property.computed ? "computed " : "",
 493                         key: getKey(property)
 494                     },
 495                     fix
 496                 });
 497             }
 498         }
 499
 500         /**
 501          * Gets the number of characters in a key, including quotes around string
 502          * keys and braces around computed property keys.
 503          * @param {ASTNode} property Property of on object literal.
 504          * @returns {int} Width of the key.
 505          */
 506         function getKeyWidth(property) {
 507             const startToken = sourceCode.getFirstToken(property);
 508             const endToken = getLastTokenBeforeColon(property.key);
 509
 510             return endToken.range[1] - startToken.range[0];
 511         }
 512
 513         /**
 514          * Gets the whitespace around the colon in an object literal property.
 515          * @param {ASTNode} property Property node from an object literal.
 516          * @returns {Object} Whitespace before and after the property's colon.
 517          */
 518         function getPropertyWhitespace(property) {
 519             const whitespace = /(\s*):(\s*)/u.exec(sourceCode.getText().slice(
 520                 property.key.range[1], property.value.range[0]
 521             ));
 522
 523             if (whitespace) {
 524                 return {
 525                     beforeColon: whitespace[1],
 526                     afterColon: whitespace[2]
 527                 };
 528             }
 529             return null;
 530         }
 531
 532         /**
 533          * Creates groups of properties.
 534          * @param {ASTNode} node ObjectExpression node being evaluated.
 535          * @returns {Array<ASTNode[]>} Groups of property AST node lists.
 536          */
 537         function createGroups(node) {
 538             if (node.properties.length === 1) {
 539                 return [node.properties];
 540             }
 541
 542             return node.properties.reduce((groups, property) => {
 543                 const currentGroup = last(groups),
 544                     prev = last(currentGroup);
 545
 546                 if (!prev || continuesPropertyGroup(prev, property)) {
 547                     currentGroup.push(property);
 548                 } else {
 549                     groups.push([property]);
 550                 }
 551
 552                 return groups;
 553             }, [
 554                 []
 555             ]);
 556         }
 557
 558         /**
 559          * Verifies correct vertical alignment of a group of properties.
 560          * @param {ASTNode[]} properties List of Property AST nodes.
 561          * @returns {void}
 562          */
 563         function verifyGroupAlignment(properties) {
 564             const length = properties.length,
 565                 widths = properties.map(getKeyWidth), // Width of keys, including quotes
 566                 align = alignmentOptions.on; // "value" or "colon"
 567             let targetWidth = Math.max(...widths),
 568                 beforeColon, afterColon, mode;
 569
 570             if (alignmentOptions && length > 1) { // When aligning values within a group, use the alignment configuration.
 571                 beforeColon = alignmentOptions.beforeColon;
 572                 afterColon = alignmentOptions.afterColon;
 573                 mode = alignmentOptions.mode;
 574             } else {
 575                 beforeColon = multiLineOptions.beforeColon;
 576                 afterColon = multiLineOptions.afterColon;
 577                 mode = alignmentOptions.mode;
 578             }
 579
 580             // Conditionally include one space before or after colon
 581             targetWidth += (align === "colon" ? beforeColon : afterColon);
 582
 583             for (let i = 0; i < length; i++) {
 584                 const property = properties[i];
 585                 const whitespace = getPropertyWhitespace(property);
 586
 587                 if (whitespace) { // Object literal getters/setters lack a colon
 588                     const width = widths[i];
 589
 590                     if (align === "value") {
 591                         report(property, "key", whitespace.beforeColon, beforeColon, mode);
 592                         report(property, "value", whitespace.afterColon, targetWidth - width, mode);
 593                     } else { // align = "colon"
 594                         report(property, "key", whitespace.beforeColon, targetWidth - width, mode);
 595                         report(property, "value", whitespace.afterColon, afterColon, mode);
 596                     }
 597                 }
 598             }
 599         }
 600
 601         /**
 602          * Verifies spacing of property conforms to specified options.
 603          * @param {ASTNode} node Property node being evaluated.
 604          * @param {Object} lineOptions Configured singleLine or multiLine options
 605          * @returns {void}
 606          */
 607         function verifySpacing(node, lineOptions) {
 608             const actual = getPropertyWhitespace(node);
 609
 610             if (actual) { // Object literal getters/setters lack colons
 611                 report(node, "key", actual.beforeColon, lineOptions.beforeColon, lineOptions.mode);
 612                 report(node, "value", actual.afterColon, lineOptions.afterColon, lineOptions.mode);
 613             }
 614         }
 615
 616         /**
 617          * Verifies spacing of each property in a list.
 618          * @param {ASTNode[]} properties List of Property AST nodes.
 619          * @param {Object} lineOptions Configured singleLine or multiLine options
 620          * @returns {void}
 621          */
 622         function verifyListSpacing(properties, lineOptions) {
 623             const length = properties.length;
 624
 625             for (let i = 0; i < length; i++) {
 626                 verifySpacing(properties[i], lineOptions);
 627             }
 628         }
 629
 630         /**
 631          * Verifies vertical alignment, taking into account groups of properties.
 632          * @param {ASTNode} node ObjectExpression node being evaluated.
 633          * @returns {void}
 634          */
 635         function verifyAlignment(node) {
 636             createGroups(node).forEach(group => {
 637                 const properties = group.filter(isKeyValueProperty);
 638
 639                 if (properties.length > 0 && isSingleLineProperties(properties)) {
 640                     verifyListSpacing(properties, multiLineOptions);
 641                 } else {
 642                     verifyGroupAlignment(properties);
 643                 }
 644             });
 645         }
 646
 647         //--------------------------------------------------------------------------
 648         // Public API
 649         //--------------------------------------------------------------------------
 650
 651         if (alignmentOptions) { // Verify vertical alignment
 652
 653             return {
 654                 ObjectExpression(node) {
 655                     if (isSingleLine(node)) {
 656                         verifyListSpacing(node.properties.filter(isKeyValueProperty), singleLineOptions);
 657                     } else {
 658                         verifyAlignment(node);
 659                     }
 660                 }
 661             };
 662
 663         }
 664
 665         // Obey beforeColon and afterColon in each property as configured
 666         return {
 667             Property(node) {
 668                 verifySpacing(node, isSingleLine(node.parent) ? singleLineOptions : multiLineOptions);
 669             }
 670         };
 671
 672
 673     }
 674 };