Merge pull request #172 from twbs/fix-29

Node.js version: implement reporting of locations of problematic elements

Author: cvrebert

README.md

@@ -58,6 +58,7 @@ Bootlint represents the lint problems it reports using the `LintError` and `Lint
     * `id` - Unique string ID for this type of lint problem. Of the form "W###" (e.g. "W123").
     * `message` - Human-readable string describing the problem
     * `elements` - jQuery or Cheerio collection of referenced DOM elements pointing to all problem locations in the document
+      * (**Only available under Node.js**): When available from the underlying HTML parser (which is most of the time), the DOM elements in the collection will have a `.startLocation` property that is a `Location` (see below) indicating the location of the element in the document's HTML source
 * `LintError`
   * Represents an error. Under the assumptions explained in the above "Caveats" section, it should never have any false-positives.
   * Constructor: `LintError(id, message, elements)`
@@ -66,6 +67,14 @@ Bootlint represents the lint problems it reports using the `LintError` and `Lint
     * `message` - Human-readable string describing the problem
     * `elements` - jQuery or Cheerio collection of referenced DOM elements pointing to all problem locations in the document
 
+Bootlint defines the following public utility class:
+* `Location` (**Only available under Node.js**)
+  * Represents a location in the HTML source
+  * Constructor: `Location(line, column)`
+  * Properties:
+    * `line` - 0-based line number
+    * `column` - 0-based column number
+
 A ***reporter*** is a function that accepts exactly 1 argument of type `LintWarning` or `LintError`. Its return value is ignored. It should somehow record the problem or display it to the user.
 
 ### Browser

package.json

@@ -46,6 +46,7 @@
     "time-grunt": "^1.0.0"
   },
   "dependencies": {
+    "binary-search": "^1.2.0",
     "body-parser": "^1.9.2",
     "chalk": "^0.5.1",
     "cheerio": "^0.18.0",
@@ -62,7 +63,8 @@
   },
   "browser": {
     "cheerio": "jquery",
-    "src/cli.js": false
+    "src/cli.js": false,
+    "src/location.js": false
   },
   "files": [
     "bin",

src/bootlint.js

@@ -9,6 +9,8 @@
 
 var cheerio = require('cheerio');
 var semver = require('semver');
+var _location = require('./location');
+var LocationIndex = _location.LocationIndex;
 
 (function (exports) {
     'use strict';
@@ -753,14 +755,29 @@ var semver = require('semver');
         }
     });
 
-    exports._lint = function ($, reporter, disabledIdList) {
+    exports._lint = function ($, reporter, disabledIdList, html) {
+        var locationIndex = IN_NODE_JS ? new LocationIndex(html) : null;
+        var reporterWrapper = IN_NODE_JS ? function (problem) {
+            if (problem.elements) {
+                problem.elements = problem.elements.each(function (i, element) {
+                    if (element.startIndex !== undefined) {
+                        var location = locationIndex.locationOf(element.startIndex);
+                        if (location) {
+                            element.startLocation = location;
+                        }
+                    }
+                });
+            }
+            reporter(problem);
+        } : reporter;
+
         var disabledIdSet = {};
         disabledIdList.forEach(function (disabledId) {
             disabledIdSet[disabledId] = true;
         });
         Object.keys(allLinters).sort().forEach(function (linterId) {
             if (!disabledIdSet[linterId]) {
-                allLinters[linterId]($, reporter);
+                allLinters[linterId]($, reporterWrapper);
             }
         });
     };
@@ -775,7 +792,7 @@ var semver = require('semver');
          */
         exports.lintHtml = function (html, reporter, disabledIds) {
             var $ = cheerio.load(html, {withStartIndices: true});
-            this._lint($, reporter, disabledIds);
+            this._lint($, reporter, disabledIds, html);
         };
     }
     else {

src/cli.js

@@ -27,8 +27,19 @@ program.args.forEach(function (pattern) {
     filenames.forEach(function (filename) {
         var reporter = function (lint) {
             var lintId = (lint.id[0] === 'E') ? chalk.bgGreen.white(lint.id) : chalk.bgRed.white(lint.id);
-            console.log(filename + ":", lintId, lint.message);
-            totalErrCount++;
+            var output = false;
+            if (lint.elements) {
+                lint.elements.each(function (_, element) {
+                    var loc = element.startLocation;
+                    console.log(filename + ":" + (loc.line + 1) + ":" + (loc.column + 1), lintId, lint.message);
+                    totalErrCount++;
+                    output = true;
+                });
+            }
+            if (!output) {
+                console.log(filename + ":", lintId, lint.message);
+                totalErrCount++;
+            }
         };
 
         var html = null;

src/location.js

@@ -0,0 +1,82 @@
+/*eslint-env node */
+var binarySearch = require('binary-search');
+
+(function () {
+    'use strict';
+
+    /*
+     * line is a 0-based line index
+     * column is a 0-based column index
+     */
+    function Location(line, column) {
+        this.line = line;
+        this.column = column;
+    }
+    exports.Location = Location;
+
+    /**
+     * Maps code unit indices into the string to line numbers and column numbers.
+     * @param {string} String to construct the index for
+     */
+    function LocationIndex(string) {
+        // ensure newline termination
+        if (string[string.length - 1] !== '\n') {
+            string += '\n';
+        }
+        this._stringLength = string.length;
+        /**
+         * Each triple in _lineStartEndTriples consists of:
+         * [0], the 0-based line index of the line the triple represents
+         * [1], the 0-based code unit index (into the string) of the start of the line (inclusive)
+         * [2], the 0-based code unit index (into the string) of the start of the next line (or the length of the string, if it is the last line)
+         * A line starts with a non-newline character,
+         * and always ends in a newline character, unless it is the very last line in the string.
+         */
+        this._lineStartEndTriples = [[0, 0]];
+        var nextLineIndex = 1;
+        var charIndex = 0;
+        while (charIndex < string.length) {
+            charIndex = string.indexOf("\n", charIndex);
+            if (charIndex === -1) {
+                break;
+            }
+            charIndex++;// go past the newline
+            this._lineStartEndTriples[this._lineStartEndTriples.length - 1].push(charIndex);
+            this._lineStartEndTriples.push([nextLineIndex, charIndex]);
+
+            nextLineIndex++;
+        }
+        this._lineStartEndTriples.pop();
+    }
+    exports.LocationIndex = LocationIndex;
+
+    /**
+     * Translates a code unit index into its corresponding Location (line index and column index) within the string
+     * @param {integer} 0-based code unit index into the string
+     * @returns {Location|null} A Location corresponding to the index, or null if the index is out of bounds
+     */
+    LocationIndex.prototype.locationOf = function (charIndex) {
+        if (charIndex < 0 || charIndex >= this._stringLength) {
+            return null;
+        }
+        var index = binarySearch(this._lineStartEndTriples, charIndex, function (bucket, needle) {
+            if (needle < bucket[1]) {
+                return 1;
+            }
+            else if (needle >= bucket[2]) {
+                return -1;
+            }
+            else {
+                return 0;
+            }
+        });
+        if (index < 0) { // binarySearch returns a negative number (but not necessarily -1) when match not found
+            return null;
+        }
+        var lineStartEnd = this._lineStartEndTriples[index];
+        var lineIndex = lineStartEnd[0];
+        var lineStartIndex = lineStartEnd[1];
+        var columnIndex = charIndex - lineStartIndex;
+        return new Location(lineIndex, columnIndex);
+    };
+})();