diff options
Diffstat (limited to 'tools/eslint/node_modules/vfile')
| -rw-r--r-- | tools/eslint/node_modules/vfile/history.md | 56 | ||||
| -rw-r--r-- | tools/eslint/node_modules/vfile/index.js | 809 | ||||
| -rw-r--r-- | tools/eslint/node_modules/vfile/package.json | 46 | ||||
| -rw-r--r-- | tools/eslint/node_modules/vfile/readme.md | 626 |
4 files changed, 1093 insertions, 444 deletions
diff --git a/tools/eslint/node_modules/vfile/history.md b/tools/eslint/node_modules/vfile/history.md new file mode 100644 index 0000000000..2f6fd078b9 --- /dev/null +++ b/tools/eslint/node_modules/vfile/history.md @@ -0,0 +1,56 @@ +<!--remark setext--> + +<!--lint disable no-multiple-toplevel-headings--> + +1.4.0 / 2016-04-18 +================== + +* Add support for passing `ruleId` to `message()` ([`77547fb`](https://github.com/wooorm/vfile/commit/77547fb)) + +1.3.1 / 2016-01-21 +================== + +1.3.0 / 2016-01-21 +================== + +* Refactor API signatures in `readme.md` ([`d41883c`](https://github.com/wooorm/vfile/commit/d41883c)) +* Add npm deployment to Travis ([`0d236c0`](https://github.com/wooorm/vfile/commit/0d236c0)) +* Update metadata in `package.json` ([`9726eec`](https://github.com/wooorm/vfile/commit/9726eec)) +* Refactor to replace mocha with tape ([`05d29df`](https://github.com/wooorm/vfile/commit/05d29df)) +* Update dev-dependencies ([`6255dd9`](https://github.com/wooorm/vfile/commit/6255dd9)) +* Add new `basename` method ([`07b79af`](https://github.com/wooorm/vfile/commit/07b79af)) + +1.2.0 / 2015-12-27 +================== + +* Update list of related tools ([`69e576f`](https://github.com/wooorm/vfile/commit/69e576f)) +* Remove distribution files from source ([`b45c780`](https://github.com/wooorm/vfile/commit/b45c780)) +* Remove support for bower ([`849c3ad`](https://github.com/wooorm/vfile/commit/849c3ad)) +* Rename mdast to remark ([`b3c8cea`](https://github.com/wooorm/vfile/commit/b3c8cea)) + +1.1.2 / 2015-10-16 +================== + +* Fix missing `Error` properties on `VFileMessage` ([`c896cf9`](https://github.com/wooorm/vfile/commit/c896cf9)) + +1.1.1 / 2015-10-14 +================== + +* Fix Safari 9 ([`bcb7a61`](https://github.com/wooorm/vfile/commit/bcb7a61)) +* Add `convert-vinyl-to-vfile` to related tools ([`1423652`](https://github.com/wooorm/vfile/commit/1423652)) + +1.1.0 / 2015-08-21 +================== + +* Add extensive location information to messages ([`848aef7`](https://github.com/wooorm/vfile/commit/848aef7)) +* Add history tracking ([`67d0112`](https://github.com/wooorm/vfile/commit/67d0112)) + +1.0.1 / 2015-08-17 +================== + +* Add list of related tools to `readme.md` ([`863df04`](https://github.com/wooorm/vfile/commit/863df04)) +* Update dependencies ([`5184aec`](https://github.com/wooorm/vfile/commit/5184aec)) +* Update documentation with difference from vinyl ([`76e1d39`](https://github.com/wooorm/vfile/commit/76e1d39)) + +1.0.0 / 2015-07-26 +================== diff --git a/tools/eslint/node_modules/vfile/index.js b/tools/eslint/node_modules/vfile/index.js index bc5b0ef853..7d775cebf8 100644 --- a/tools/eslint/node_modules/vfile/index.js +++ b/tools/eslint/node_modules/vfile/index.js @@ -1,261 +1,628 @@ +/** + * @author Titus Wormer + * @copyright 2015 Titus Wormer + * @license MIT + * @module vfile + * @fileoverview Virtual file format to attach additional + * information related to processed input. Similar to + * `wearefractal/vinyl`. Additionally, `VFile` can be + * passed directly to ESLint formatters to visualise + * warnings and errors relating to a file. + * @example + * var VFile = require('vfile'); + * + * var file = new VFile({ + * 'directory': '~', + * 'filename': 'example', + * 'extension': 'txt', + * 'contents': 'Foo *bar* baz' + * }); + * + * file.toString(); // 'Foo *bar* baz' + * file.filePath(); // '~/example.txt' + * + * file.move({'extension': 'md'}); + * file.filePath(); // '~/example.md' + * + * file.warn('Something went wrong', {'line': 2, 'column': 3}); + * // { [~/example.md:2:3: Something went wrong] + * // name: '~/example.md:2:3', + * // file: '~/example.md', + * // reason: 'Something went wrong', + * // line: 2, + * // column: 3, + * // fatal: false } + */ + 'use strict'; -var path = require('path'); -var replace = require('replace-ext'); -var stringify = require('unist-util-stringify-position'); -var buffer = require('is-buffer'); +/* eslint-env commonjs */ -module.exports = VFile; +var proto; -var own = {}.hasOwnProperty; -var proto = VFile.prototype; +var SEPARATOR = '/'; -proto.toString = toString; -proto.message = message; -proto.fail = fail; +try { + SEPARATOR = require('pa' + 'th').sep; +} catch (e) { /* empty */ } + +/** + * Construct a new file message. + * + * Note: We cannot invoke `Error` on the created context, + * as that adds readonly `line` and `column` attributes on + * Safari 9, thus throwing and failing the data. + * + * @example + * var message = new VFileMessage('Whoops!'); + * + * message instanceof Error // true + * + * @constructor + * @class {VFileMessage} + * @param {string} reason - Reason for messaging. + * @property {boolean} [fatal=null] - Whether the message + * is fatal. + * @property {string} [name=''] - File-name and positional + * information. + * @property {string} [file=''] - File-path. + * @property {string} [reason=''] - Reason for messaging. + * @property {number} [line=null] - Start of message. + * @property {number} [column=null] - Start of message. + * @property {Position|Location} [location=null] - Place of + * message. + * @property {string} [stack] - Stack-trace of warning. + */ +function VFileMessage(reason) { + this.message = reason; +} + +/** + * Inherit from `Error#`. + */ +function VFileMessagePrototype() {} + +VFileMessagePrototype.prototype = Error.prototype; + +proto = new VFileMessagePrototype(); + +VFileMessage.prototype = proto; + +/* + * Expose defaults. + */ + +proto.file = proto.name = proto.reason = proto.message = proto.stack = ''; +proto.fatal = proto.column = proto.line = null; + +/** + * File-related message with location information. + * + * @typedef {Error} VFileMessage + * @property {string} name - (Starting) location of the + * message, preceded by its file-path when available, + * and joined by `:`. Used internally by the native + * `Error#toString()`. + * @property {string} file - File-path. + * @property {string} reason - Reason for message. + * @property {number?} line - Line of message, when + * available. + * @property {number?} column - Column of message, when + * available. + * @property {string?} stack - Stack of message, when + * available. + * @property {boolean?} fatal - Whether the associated file + * is still processable. + */ + +/** + * Stringify a position. + * + * @example + * stringify({'line': 1, 'column': 3}) // '1:3' + * stringify({'line': 1}) // '1:1' + * stringify({'column': 3}) // '1:3' + * stringify() // '1:1' + * + * @private + * @param {Object?} [position] - Single position, like + * those available at `node.position.start`. + * @return {string} - Compiled location. + */ +function stringify(position) { + if (!position) { + position = {}; + } -/* Slight backwards compatibility. Remove in the future. */ -proto.warn = message; - -/* Order of setting (least specific to most), we need this because - * otherwise `{stem: 'a', path: '~/b.js'}` would throw, as a path - * is needed before a stem can be set. */ -var order = [ - 'history', - 'path', - 'basename', - 'stem', - 'extname', - 'dirname' -]; - -/* Construct a new file. */ + return (position.line || 1) + ':' + (position.column || 1); +} + +/** + * ESLint's formatter API expects `filePath` to be a + * string. This hack supports invocation as well as + * implicit coercion. + * + * @example + * var file = new VFile({ + * 'filename': 'example', + * 'extension': 'txt' + * }); + * + * filePath = filePathFactory(file); + * + * String(filePath); // 'example.txt' + * filePath(); // 'example.txt' + * + * @private + * @param {VFile} file - Virtual file. + * @return {Function} - `filePath` getter. + */ +function filePathFactory(file) { + /** + * Get the filename, with extension and directory, if applicable. + * + * @example + * var file = new VFile({ + * 'directory': '~', + * 'filename': 'example', + * 'extension': 'txt' + * }); + * + * String(file.filePath); // ~/example.txt + * file.filePath() // ~/example.txt + * + * @memberof {VFile} + * @property {Function} toString - Itself. ESLint's + * formatter API expects `filePath` to be `string`. + * This hack supports invocation as well as implicit + * coercion. + * @return {string} - If the `vFile` has a `filename`, + * it will be prefixed with the directory (slashed), + * if applicable, and suffixed with the (dotted) + * extension (if applicable). Otherwise, an empty + * string is returned. + */ + function filePath() { + var directory = file.directory; + var separator; + + if (file.filename || file.extension) { + separator = directory.charAt(directory.length - 1); + + if (separator === '/' || separator === '\\') { + directory = directory.slice(0, -1); + } + + if (directory === '.') { + directory = ''; + } + + return (directory ? directory + SEPARATOR : '') + + file.filename + + (file.extension ? '.' + file.extension : ''); + } + + return ''; + } + + filePath.toString = filePath; + + return filePath; +} + +/** +* Get the filename with extantion. +* +* @example +* var file = new VFile({ +* 'directory': '~/foo/bar' +* 'filename': 'example', +* 'extension': 'txt' +* }); +* +* file.basename() // example.txt +* +* @memberof {VFile} +* @return {string} - name of file with extantion. +*/ +function basename() { + var self = this; + var extension = self.extension; + + if (self.filename || extension) { + return self.filename + (extension ? '.' + extension : ''); + } + + return ''; +} + +/** + * Construct a new file. + * + * @example + * var file = new VFile({ + * 'directory': '~', + * 'filename': 'example', + * 'extension': 'txt', + * 'contents': 'Foo *bar* baz' + * }); + * + * file === VFile(file) // true + * file === new VFile(file) // true + * VFile('foo') instanceof VFile // true + * + * @constructor + * @class {VFile} + * @param {Object|VFile|string} [options] - either an + * options object, or the value of `contents` (both + * optional). When a `file` is passed in, it's + * immediately returned. + * @property {string} [contents=''] - Content of file. + * @property {string} [directory=''] - Path to parent + * directory. + * @property {string} [filename=''] - Filename. + * A file-path can still be generated when no filename + * exists. + * @property {string} [extension=''] - Extension. + * A file-path can still be generated when no extension + * exists. + * @property {boolean?} quiet - Whether an error created by + * `VFile#fail()` is returned (when truthy) or thrown + * (when falsey). Ensure all `messages` associated with + * a file are handled properly when setting this to + * `true`. + * @property {Array.<VFileMessage>} messages - List of associated + * messages. + */ function VFile(options) { - var prop; - var index; - var length; - - if (!options) { - options = {}; - } else if (typeof options === 'string' || buffer(options)) { - options = {contents: options}; - } else if ('message' in options && 'messages' in options) { - return options; - } - - if (!(this instanceof VFile)) { - return new VFile(options); - } - - this.data = {}; - this.messages = []; - this.history = []; - this.cwd = process.cwd(); - - /* Set path related properties in the correct order. */ - index = -1; - length = order.length; - - while (++index < length) { - prop = order[index]; - - if (own.call(options, prop)) { - this[prop] = options[prop]; + var self = this; + + /* + * No `new` operator. + */ + + if (!(self instanceof VFile)) { + return new VFile(options); + } + + /* + * Given file. + */ + + if ( + options && + typeof options.message === 'function' && + typeof options.hasFailed === 'function' + ) { + return options; } - } - /* Set non-path related properties. */ - for (prop in options) { - if (order.indexOf(prop) === -1) { - this[prop] = options[prop]; + if (!options) { + options = {}; + } else if (typeof options === 'string') { + options = { + 'contents': options + }; } - } + + self.contents = options.contents || ''; + + self.messages = []; + + /* + * Make sure eslint’s formatters stringify `filePath` + * properly. + */ + + self.filePath = filePathFactory(self); + + self.history = []; + + self.move({ + 'filename': options.filename, + 'directory': options.directory, + 'extension': options.extension + }); } -/* Access full path (`~/index.min.js`). */ -Object.defineProperty(proto, 'path', { - get: function () { - return this.history[this.history.length - 1]; - }, - set: function (path) { - assertNonEmpty(path, 'path'); +/** + * Get the value of the file. + * + * @example + * var vFile = new VFile('Foo'); + * String(vFile); // 'Foo' + * + * @this {VFile} + * @memberof {VFile} + * @return {string} - value at the `contents` property + * in context. + */ +function toString() { + return this.contents; +} - if (path !== this.path) { - this.history.push(path); +/** + * Move a file by passing a new directory, filename, + * and extension. When these are not given, the default + * values are kept. + * + * @example + * var file = new VFile({ + * 'directory': '~', + * 'filename': 'example', + * 'extension': 'txt', + * 'contents': 'Foo *bar* baz' + * }); + * + * file.move({'directory': '/var/www'}); + * file.filePath(); // '/var/www/example.txt' + * + * file.move({'extension': 'md'}); + * file.filePath(); // '/var/www/example.md' + * + * @this {VFile} + * @memberof {VFile} + * @param {Object?} [options] - Configuration. + * @return {VFile} - Context object. + */ +function move(options) { + var self = this; + var before = self.filePath(); + var after; + + if (!options) { + options = {}; } - } -}); - -/* Access parent path (`~`). */ -Object.defineProperty(proto, 'dirname', { - get: function () { - return typeof this.path === 'string' ? path.dirname(this.path) : undefined; - }, - set: function (dirname) { - assertPath(this.path, 'dirname'); - this.path = path.join(dirname || '', this.basename); - } -}); - -/* Access basename (`index.min.js`). */ -Object.defineProperty(proto, 'basename', { - get: function () { - return typeof this.path === 'string' ? path.basename(this.path) : undefined; - }, - set: function (basename) { - assertNonEmpty(basename, 'basename'); - assertPart(basename, 'basename'); - this.path = path.join(this.dirname || '', basename); - } -}); - -/* Access extname (`.js`). */ -Object.defineProperty(proto, 'extname', { - get: function () { - return typeof this.path === 'string' ? path.extname(this.path) : undefined; - }, - set: function (extname) { - var ext = extname || ''; - - assertPart(ext, 'extname'); - assertPath(this.path, 'extname'); - - if (ext) { - if (ext.charAt(0) !== '.') { - throw new Error('`extname` must start with `.`'); - } - - if (ext.indexOf('.', 1) !== -1) { - throw new Error('`extname` cannot contain multiple dots'); - } + + self.directory = options.directory || self.directory || ''; + self.filename = options.filename || self.filename || ''; + self.extension = options.extension || self.extension || ''; + + after = self.filePath(); + + if (after && before !== after) { + self.history.push(after); } - this.path = replace(this.path, ext); - } -}); - -/* Access stem (`index.min`). */ -Object.defineProperty(proto, 'stem', { - get: function () { - return typeof this.path === 'string' ? path.basename(this.path, this.extname) : undefined; - }, - set: function (stem) { - assertNonEmpty(stem, 'stem'); - assertPart(stem, 'stem'); - this.path = path.join(this.dirname || '', stem + (this.extname || '')); - } -}); - -/* Get the value of the file. */ -function toString(encoding) { - var value = this.contents || ''; - return buffer(value) ? value.toString(encoding) : String(value); + return self; } -/* Create a message with `reason` at `position`. +/** + * Create a message with `reason` at `position`. * When an error is passed in as `reason`, copies the - * stack. This does not add a message to `messages`. */ + * stack. This does not add a message to `messages`. + * + * @example + * var file = new VFile(); + * + * file.message('Something went wrong'); + * // { [1:1: Something went wrong] + * // name: '1:1', + * // file: '', + * // reason: 'Something went wrong', + * // line: null, + * // column: null } + * + * @this {VFile} + * @memberof {VFile} + * @param {string|Error} reason - Reason for message. + * @param {Node|Location|Position} [position] - Location + * of message in file. + * @param {string} [ruleId] - Category of warning. + * @return {VFileMessage} - File-related message with + * location information. + */ function message(reason, position, ruleId) { - var filePath = this.path; - var range = stringify(position) || '1:1'; - var location; - var err; - - location = { - start: {line: null, column: null}, - end: {line: null, column: null} - }; - - if (position && position.position) { - position = position.position; - } - - if (position) { - /* Location. */ - if (position.start) { - location = position; - position = position.start; - } else { - /* Position. */ - location.start = position; + var filePath = this.filePath(); + var range; + var err; + var location = { + 'start': { + 'line': null, + 'column': null + }, + 'end': { + 'line': null, + 'column': null + } + }; + + /* + * Node / location / position. + */ + + if (position && position.position) { + position = position.position; } - } - err = new VMessage(reason.message || reason); + if (position && position.start) { + range = stringify(position.start) + '-' + stringify(position.end); + location = position; + position = position.start; + } else { + range = stringify(position); - err.name = (filePath ? filePath + ':' : '') + range; - err.file = filePath || ''; - err.reason = reason.message || reason; - err.line = position ? position.line : null; - err.column = position ? position.column : null; - err.location = location; - err.ruleId = ruleId || null; - err.source = null; - err.fatal = false; + if (position) { + location.start = position; + location.end.line = null; + location.end.column = null; + } + } - if (reason.stack) { - err.stack = reason.stack; - } + err = new VFileMessage(reason.message || reason); - this.messages.push(err); + err.name = (filePath ? filePath + ':' : '') + range; + err.file = filePath; + err.reason = reason.message || reason; + err.line = position ? position.line : null; + err.column = position ? position.column : null; + err.location = location; + err.ruleId = ruleId || null; - return err; + if (reason.stack) { + err.stack = reason.stack; + } + + return err; } -/* Fail. Creates a vmessage, associates it with the file, - * and throws it. */ -function fail() { - var message = this.message.apply(this, arguments); +/** + * Warn. Creates a non-fatal message (see `VFile#message()`), + * and adds it to the file's `messages` list. + * + * @example + * var file = new VFile(); + * + * file.warn('Something went wrong'); + * // { [1:1: Something went wrong] + * // name: '1:1', + * // file: '', + * // reason: 'Something went wrong', + * // line: null, + * // column: null, + * // fatal: false } + * + * @see VFile#message + * @this {VFile} + * @memberof {VFile} + */ +function warn() { + var err = this.message.apply(this, arguments); + + err.fatal = false; - message.fatal = true; + this.messages.push(err); - throw message; + return err; } -/* Inherit from `Error#`. */ -function VMessagePrototype() {} -VMessagePrototype.prototype = Error.prototype; -VMessage.prototype = new VMessagePrototype(); - -/* Message properties. */ -proto = VMessage.prototype; +/** + * Fail. Creates a fatal message (see `VFile#message()`), + * sets `fatal: true`, adds it to the file's + * `messages` list. + * + * If `quiet` is not `true`, throws the error. + * + * @example + * var file = new VFile(); + * + * file.fail('Something went wrong'); + * // 1:1: Something went wrong + * // at VFile.exception (vfile/index.js:296:11) + * // at VFile.fail (vfile/index.js:360:20) + * // at repl:1:6 + * + * file.quiet = true; + * file.fail('Something went wrong'); + * // { [1:1: Something went wrong] + * // name: '1:1', + * // file: '', + * // reason: 'Something went wrong', + * // line: null, + * // column: null, + * // fatal: true } + * + * @this {VFile} + * @memberof {VFile} + * @throws {VFileMessage} - When not `quiet: true`. + * @param {string|Error} reason - Reason for failure. + * @param {Node|Location|Position} [position] - Place + * of failure in file. + * @return {VFileMessage} - Unless thrown, of course. + */ +function fail(reason, position) { + var err = this.message(reason, position); + + err.fatal = true; + + this.messages.push(err); + + if (!this.quiet) { + throw err; + } -proto.file = ''; -proto.name = ''; -proto.reason = ''; -proto.message = ''; -proto.stack = ''; -proto.fatal = null; -proto.column = null; -proto.line = null; + return err; +} -/* Construct a new file message. +/** + * Check if a fatal message occurred making the file no + * longer processable. * - * Note: We cannot invoke `Error` on the created context, - * as that adds readonly `line` and `column` attributes on - * Safari 9, thus throwing and failing the data. */ -function VMessage(reason) { - this.message = reason; -} + * @example + * var file = new VFile(); + * file.quiet = true; + * + * file.hasFailed(); // false + * + * file.fail('Something went wrong'); + * file.hasFailed(); // true + * + * @this {VFile} + * @memberof {VFile} + * @return {boolean} - `true` if at least one of file's + * `messages` has a `fatal` property set to `true` + */ +function hasFailed() { + var messages = this.messages; + var index = -1; + var length = messages.length; + + while (++index < length) { + if (messages[index].fatal) { + return true; + } + } -/* Assert that `part` is not a path (i.e., does - * not contain `path.sep`). */ -function assertPart(part, name) { - if (part.indexOf(path.sep) !== -1) { - throw new Error('`' + name + '` cannot be a path: did not expect `' + path.sep + '`'); - } + return false; } -/* Assert that `part` is not empty. */ -function assertNonEmpty(part, name) { - if (!part) { - throw new Error('`' + name + '` cannot be empty'); - } -} +/** + * Access metadata. + * + * @example + * var file = new VFile('Foo'); + * + * file.namespace('foo').bar = 'baz'; + * + * console.log(file.namespace('foo').bar) // 'baz'; + * + * @this {VFile} + * @memberof {VFile} + * @param {string} key - Namespace key. + * @return {Object} - Private space. + */ +function namespace(key) { + var self = this; + var space = self.data; + + if (!space) { + space = self.data = {}; + } + + if (!space[key]) { + space[key] = {}; + } -/* Assert `path` exists. */ -function assertPath(path, name) { - if (!path) { - throw new Error('Setting `' + name + '` requires `path` to be set too'); - } + return space[key]; } + +/* + * Methods. + */ + +proto = VFile.prototype; + +proto.basename = basename; +proto.move = move; +proto.toString = toString; +proto.message = message; +proto.warn = warn; +proto.fail = fail; +proto.hasFailed = hasFailed; +proto.namespace = namespace; + +/* + * Expose. + */ + +module.exports = VFile; diff --git a/tools/eslint/node_modules/vfile/package.json b/tools/eslint/node_modules/vfile/package.json index 683037519b..64820cb423 100644 --- a/tools/eslint/node_modules/vfile/package.json +++ b/tools/eslint/node_modules/vfile/package.json @@ -28,7 +28,7 @@ "url": "http://wooorm.com" }, "bugs": { - "url": "https://github.com/vfile/vfile/issues" + "url": "https://github.com/wooorm/vfile/issues" }, "bundleDependencies": false, "contributors": [ @@ -36,29 +36,14 @@ "name": "Titus Wormer", "email": "tituswormer@gmail.com", "url": "http://wooorm.com" - }, - { - "name": "Denys Dovhan", - "email": "email@denysdovhan.com" - }, - { - "name": "Kyle Mathews", - "email": "mathews.kyle@gmail.com" - }, - { - "name": "Shinnosuke Watanabe", - "email": "snnskwtnb@gmail.com" - }, - { - "name": "Sindre Sorhus", - "email": "sindresorhus@gmail.com" } ], "dependencies": {}, "deprecated": false, "description": "Virtual file format for text processing", "devDependencies": { - "browserify": "^14.0.0", + "browserify": "^13.0.0", + "eslint": "^2.0.0", "esmangle": "^1.0.0", "istanbul": "^0.4.0", "jscs": "^3.0.0", @@ -91,27 +76,20 @@ "name": "vfile", "repository": { "type": "git", - "url": "git+https://github.com/vfile/vfile.git" + "url": "git+https://github.com/wooorm/vfile.git" }, "scripts": { "build": "npm run build-md && npm run build-bundle && npm run build-mangle", "build-bundle": "browserify index.js -s VFile > vfile.js", "build-mangle": "esmangle vfile.js > vfile.min.js", - "build-md": "remark . -qfo", - "lint": "xo", + "build-md": "remark . --quiet --frail", + "lint": "npm run lint-api && npm run lint-style", + "lint-api": "eslint .", + "lint-style": "jscs --reporter inline .", "test": "npm run build && npm run lint && npm run test-coverage", - "test-api": "node test", - "test-coverage": "nyc --reporter lcov tape test.js" + "test-api": "node test.js", + "test-coverage": "istanbul cover test.js", + "test-travis": "npm run test-coverage" }, - "version": "2.1.0", - "xo": { - "space": true, - "esnext": false, - "rules": { - "unicorn/no-new-buffer": "off" - }, - "ignores": [ - "vfile.js" - ] - } + "version": "1.4.0" } diff --git a/tools/eslint/node_modules/vfile/readme.md b/tools/eslint/node_modules/vfile/readme.md index 38896f6940..48f5269c54 100644 --- a/tools/eslint/node_modules/vfile/readme.md +++ b/tools/eslint/node_modules/vfile/readme.md @@ -1,290 +1,538 @@ -# ![vfile][] +#  -[![Build Status][build-badge]][build-status] -[![Coverage Status][coverage-badge]][coverage-status] +[](https://travis-ci.org/wooorm/vfile) [](https://codecov.io/github/wooorm/vfile) -**VFile** is a virtual file format used by [**unified**][unified], -a text processing umbrella (it powers [**retext**][retext] for -natural language, [**remark**][remark] for markdown, and -[**rehype**][rehype] for HTML). Each processors that parse, transform, -and compile text, and need a virtual representation of files and a -place to store [messages][] about them. Plus, they work in the browser. -**VFile** provides these requirements at a small size, in IE 9 and up. +**VFile** is a virtual file format used by [**retext**](https://github.com/wooorm/retext) +(natural language) and [**remark**](https://github.com/wooorm/remark) +(markdown). Two processors which parse, transform, and compile text. Both need +a virtual representation of files and a place to store metadata and messages. +And, they work in the browser. **VFile** provides these requirements. -> **VFile** is different from the excellent [**vinyl**][vinyl] -> in that it has a smaller API, a smaller size, and focuses on -> [messages][]. +Also, **VFile** exposes a warning mechanism compatible with [**ESLint**](https://github.com/eslint/eslint)s +formatters, making it easy to expose [stylish](https://github.com/eslint/eslint/blob/master/lib/formatters/stylish.js) +warnings, or export [tap](https://github.com/eslint/eslint/blob/master/lib/formatters/tap.js) +compliant messages. + +> **VFile** is different from (the excellent :+1:) [**vinyl**](https://github.com/wearefractal/vinyl) +> in that it does not include file-system or node-only functionality. No +> buffers, streams, or stats. In addition, the focus on +> [metadata](#vfilenamespacekey) and [messages](#vfilemessagereason-position-ruleid) +> are useful when processing a file through a +> [middleware](https://github.com/segmentio/ware) pipeline. ## Installation -[npm][]: +[npm](https://docs.npmjs.com/cli/install): ```bash npm install vfile ``` +**VFile** is also available for [duo](http://duojs.org/#getting-started), +and as an AMD, CommonJS, and globals module, [uncompressed and +compressed](https://github.com/wooorm/vfile/releases). + ## Table of Contents * [Usage](#usage) -* [Utilities](#utilities) -* [Reporters](#reporters) + +* [Related Tools](#related-tools) + * [API](#api) - * [VFile(\[options\])](#vfileoptions) - * [vfile.contents](#vfilecontents) - * [vfile.cwd](#vfilecwd) - * [vfile.path](#vfilepath) - * [vfile.basename](#vfilebasename) - * [vfile.stem](#vfilestem) - * [vfile.extname](#vfileextname) - * [vfile.dirname](#vfiledirname) - * [vfile.history](#vfilehistory) - * [vfile.messages](#vfilemessages) - * [vfile.data](#vfiledata) - * [VFile#toString(\[encoding\])](#vfiletostringencoding) + + * [VFile()](#vfile-1) + * [VFile#contents](#vfilecontents) + * [VFile#directory](#vfiledirectory) + * [VFile#filename](#vfilefilename) + * [VFile#extension](#vfileextension) + * [VFile#basename()](#vfilebasename) + * [VFile#quiet](#vfilequiet) + * [VFile#messages](#vfilemessages) + * [VFile#history](#vfilehistory) + * [VFile#toString()](#vfiletostring) + * [VFile#filePath()](#vfilefilepath) + * [VFile#move(options)](#vfilemoveoptions) + * [VFile#namespace(key)](#vfilenamespacekey) * [VFile#message(reason\[, position\[, ruleId\]\])](#vfilemessagereason-position-ruleid) + * [VFile#warn(reason\[, position\[, ruleId\]\])](#vfilewarnreason-position-ruleid) * [VFile#fail(reason\[, position\[, ruleId\]\])](#vfilefailreason-position-ruleid) + * [VFile#hasFailed()](#vfilehasfailed) * [VFileMessage](#vfilemessage) + * [License](#license) ## Usage ```js -var vfile = require('vfile'); +var VFile = require('vfile'); + +var file = new VFile({ + 'directory': '~', + 'filename': 'example', + 'extension': 'txt', + 'contents': 'Foo *bar* baz' +}); + +file.toString(); // 'Foo *bar* baz' +file.filePath(); // '~/example.txt' + +file.move({'extension': 'md'}); +file.filePath(); // '~/example.md' + +file.warn('Something went wrong', {'line': 1, 'column': 3}); +// { [~/example.md:1:3: Something went wrong] +// name: '~/example.md:1:3', +// file: '~/example.md', +// reason: 'Something went wrong', +// line: 1, +// column: 3, +// fatal: false } +``` + +## Related Tools + +[**VFile**](#api)s are used by both [**retext**](https://github.com/wooorm/retext) +and [**remark**](https://github.com/wooorm/remark). + +In addition, here’s a list of useful tools: + +* [`dustinspecker/convert-vinyl-to-vfile`](https://github.com/dustinspecker/convert-vinyl-to-vfile) + — Convert a [Vinyl](https://github.com/wearefractal/vinyl) file to a VFile; + +* [`shinnn/is-vfile-message`](https://github.com/shinnn/is-vfile-message) + — Check if a value is a `VFileMessage` object; + +* [`wooorm/to-vfile`](https://github.com/wooorm/to-vfile) + — Create a virtual file from a file-path; + +* [`wooorm/vfile-find-down`](https://github.com/wooorm/vfile-find-down) + — Find one or more files by searching the file system downwards; + +* [`wooorm/vfile-find-up`](https://github.com/wooorm/vfile-find-up) + — Find one or more files by searching the file system upwards; -var file = vfile({path: '~/example.txt', contents: 'Alpha *braavo* charlie.'}); +* [`wooorm/vfile-location`](https://github.com/wooorm/vfile-location) + — Convert between positions (line and column-based) and offsets + (range-based) locations; -file.path; //=> '~/example.txt' -file.dirname; //=> '~' +* [`shinnn/vfile-messages-to-vscode-diagnostics`](https://github.com/shinnn/vfile-messages-to-vscode-diagnostics) + — Convert `VFileMessage`s into an array of VS Code diagnostics; -file.extname = '.md'; +* [`wooorm/vfile-reporter`](https://github.com/wooorm/vfile-reporter) + — Stylish reporter for virtual files. -file.basename; //=> 'example.md' +* [`wooorm/vfile-sort`](https://github.com/wooorm/vfile-sort) + — Sort virtual file messages by line/column; -file.basename = 'index.text'; +## API + +### `VFile()` + +**VFile** objects make it easy to move files, to trigger warnings and +errors, and to store supplementary metadata relating to files, all without +accessing the file-system. + +**Example**: -file.history; //=> ['~/example.txt', '~/example.md', '~/index.text'] +```js +var file = new VFile({ + 'directory': '~', + 'filename': 'example', + 'extension': 'txt', + 'contents': 'Foo *bar* baz' +}); -file.message('`braavo` is misspelt; did you mean `bravo`?', {line: 1, column: 8}); +file === VFile(file); // true +file === new VFile(file); // true -console.log(file.messages); +VFile('foo') instanceof VFile; // true ``` -Yields: +**Signatures**: + +* `file = VFile(contents|options|vFile?)`. + +**Parameters**: + +* `contents` (`string`) — Contents of the file; + +* `vFile` (`VFile`) — Existing representation, returned without modification; + +* `options` (`Object`): + + * `directory` (`string?`, default: `''`) + — Parent directory; + + * `filename` (`string?`, default: `''`) + — Name, without extension; + + * `extension` (`string?`, default: `''`) + — Extension(s), without initial dot; + + * `contents` (`string?`, default: `''`) + — Raw value. + +**Returns**: + +`vFile` — Instance. + +**Notes**: + +`VFile` exposes an interface compatible with ESLint’s formatters. For example, +to expose warnings using ESLint’s `compact` formatter, execute the following: + +```javascript +var compact = require('eslint/lib/formatters/compact'); +var VFile = require('vfile'); + +var vFile = new VFile({ + 'directory': '~', + 'filename': 'hello', + 'extension': 'txt' +}); + +vFile.warn('Whoops, something happened!'); + +console.log(compact([vFile])); +``` + +Which would yield the following: + +```text +~/hello.txt: line 0, col 0, Warning - Whoops, something happened! + +1 problem +``` + +### `VFile#contents` + +`string` — Content of file. + +### `VFile#directory` + +`string` — Path to parent directory. + +### `VFile#filename` + +`string` — Filename. A file-path can still be generated when no filename exists. + +### `VFile#extension` + +`string` — Extension. A file-path can still be generated when no extension +exists. + +### `VFile#basename()` + +Get the filename, with extension, if applicable. + +**Example**: ```js -[ { [~/index.text:1:8: `braavo` is misspelt; did you mean `bravo`?] - message: '`braavo` is misspelt; did you mean `bravo`?', - name: '~/index.text:1:8', - file: '~/index.text', - reason: '`braavo` is misspelt; did you mean `bravo`?', - line: 1, - column: 8, - location: { start: [Object], end: [Object] }, - ruleId: null, - source: null, - fatal: false } ] +var file = new VFile({ + 'directory': '~', + 'filename': 'example', + 'extension': 'txt' +}); + +file.basename() // example.txt ``` -## Utilities - -The following list of projects includes tools for working with virtual -files. See [**Unist**][unist] for projects working with nodes. - -* [`convert-vinyl-to-vfile`](https://github.com/dustinspecker/convert-vinyl-to-vfile) - — Convert from [Vinyl][] -* [`is-vfile-message`](https://github.com/shinnn/is-vfile-message) - — Check if a value is a `VFileMessage` object -* [`to-vfile`](https://github.com/vfile/to-vfile) - — Create a virtual file from a file-path (and optionally read it) -* [`vfile-find-down`](https://github.com/vfile/vfile-find-down) - — Find files by searching the file system downwards -* [`vfile-find-up`](https://github.com/vfile/vfile-find-up) - — Find files by searching the file system upwards -* [`vfile-location`](https://github.com/vfile/vfile-location) - — Convert between line/column- and range-based locations -* [`vfile-statistics`](https://github.com/vfile/vfile-statistics) - — Count messages per category -* [`vfile-messages-to-vscode-diagnostics`](https://github.com/shinnn/vfile-messages-to-vscode-diagnostics) - — Convert to VS Code diagnostics -* [`vfile-sort`](https://github.com/vfile/vfile-sort) - — Sort messages by line/column -* [`vfile-to-eslint`](https://github.com/vfile/vfile-to-eslint) - — Convert VFiles to ESLint formatter compatible output - -## Reporters - -The following list of projects show linting results for given virtual files. -Reporters _must_ accept `Array.<VFile>` as their first argument, and return -`string`. Reporters _may_ accept other values too, in which case it’s suggested -to stick to `vfile-reporter`s interface. - -* [`vfile-reporter`](https://github.com/vfile/vfile-reporter) - — Stylish reporter -* [`vfile-reporter-json`](https://github.com/vfile/vfile-reporter-json) - — JSON reporter -* [`vfile-reporter-pretty`](https://github.com/vfile/vfile-reporter-pretty) - — Pretty reporter +**Signatures**: -## API +* `string = vFile.basename()`. + +**Returns**: + +`string`— Returns the file path without a directory, if applicable. +Otherwise,an empty string is returned. + +### `VFile#quiet` + +`boolean?` — Whether an error created by [`VFile#fail()`](#vfilemessagereason-position-ruleid) +is returned (when truthy) or thrown (when falsey). -### `VFile([options])` +Ensure all `messages` associated with a file are handled properly when setting +this to `true`. -Create a new virtual file. If `options` is `string` or `Buffer`, treats -it as `{contents: options}`. If `options` is a `VFile`, returns it. -All other options are set on the newly created `vfile`. +### `VFile#messages` -Path related properties are set in the following order (least specific -to most specific): `history`, `path`, `basename`, `stem`, `extname`, -`dirname`. +`Array.<VFileMessage>` — List of associated messages. -It’s not possible to set either `dirname` or `extname` without setting -either `history`, `path`, `basename`, or `stem` as well. +**Notes**: -###### Example +`VFile#message()`, and in turn `VFile#warn()` and `VFile#fail()`, return +`Error` objects that adhere to the [`VFileMessage`](#vfilemessage) schema. +Its results can populate `messages`. + +### `VFile#history` + +`Array.<String>` — List of file-paths the file [`move`](#vfilemoveoptions)d +between. + +### `VFile#toString()` + +Get the value of the file. + +**Example**: ```js -vfile(); -vfile('console.log("alpha");'); -vfile(Buffer.from('exit 1')); -vfile({path: path.join(__dirname, 'readme.md')}); -vfile({stem: 'readme', extname: '.md', dirname: __dirname}); -vfile({other: 'properties', are: 'copied', ov: {e: 'r'}}); +var vFile = new VFile('Foo'); +String(vFile); // 'Foo' ``` -### `vfile.contents` +**Signatures**: + +* `string = vFile.toString()`. -`Buffer`, `string`, `null` — Raw value. +**Returns**: -### `vfile.cwd` +`string` — Contents. -`string` — Base of `path`. Defaults to `process.cwd()`. +### `VFile#filePath()` -### `vfile.path` +Get the filename, with extension and directory, if applicable. -`string?` — Path of `vfile`. Cannot be nullified. +**Example**: -### `vfile.basename` +```js +var file = new VFile({ + 'directory': '~', + 'filename': 'example', + 'extension': 'txt' +}); + +String(file.filePath); // ~/example.txt +file.filePath() // ~/example.txt +``` -`string?` — Current name (including extension) of `vfile`. Cannot -contain path separators. Cannot be nullified either (use -`file.path = file.dirname` instead). +**Signatures**: -### `vfile.stem` +* `string = vFile.filePath()`. -`string?` — Name (without extension) of `vfile`. Cannot be nullified, -and cannot contain path separators. +**Returns**: + +`string` — If the `vFile` has a `filename`, it will be prefixed with the +directory (slashed), if applicable, and suffixed with the (dotted) extension +(if applicable). Otherwise, an empty string is returned. + +### `VFile#move(options)` + +Move a file by passing a new directory, filename, and extension. When these +are not given, the default values are kept. + +**Example**: + +```js +var file = new VFile({ + 'directory': '~', + 'filename': 'example', + 'extension': 'txt', + 'contents': 'Foo *bar* baz' +}); + +file.move({'directory': '/var/www'}); +file.filePath(); // '/var/www/example.txt' + +file.move({'extension': 'md'}); +file.filePath(); // '/var/www/example.md' +``` -### `vfile.extname` +**Signatures**: -`string?` — Extension (with dot) of `vfile`. Cannot be set if -there’s no `path` yet and cannot contain path separators. +* `vFile = vFile.move(options?)`. -### `vfile.dirname` +**Parameters**: -`string?` — Path to parent directory of `vfile`. Cannot be set if -there’s no `path` yet. +* `options` (`Object`): -### `vfile.history` + * `directory` (`string`, default: `''`) + — Parent directory; -`Array.<string>` — List of file-paths the file moved between. + * `filename` (`string?`, default: `''`) + — Name, without extension; -### `vfile.messages` + * `extension` (`string`, default: `''`) + — Extension(s), without initial dot. -`Array.<VFileMessage>` — List of messages associated with the file. +**Returns**: -### `vfile.data` +`vFile` — Context object (chainable). -`Object` — Place to store custom information. It’s OK to store custom -data directly on the `vfile`, moving it to `data` gives a _little_ more -privacy. +### `VFile#namespace(key)` -### `VFile#toString([encoding])` +Access metadata. -Convert contents of `vfile` to string. If `contents` is a buffer, -`encoding` is used to stringify buffers (default: `'utf8'`). +**Example**: + +```js +var file = new VFile('Foo'); + +file.namespace('foo').bar = 'baz'; + +console.log(file.namespace('foo').bar) // 'baz'; +``` + +**Parameters**: + +* `key` (`string`) — Namespace key. + +**Returns**: + +`Object` — Private namespace for metadata. ### `VFile#message(reason[, position[, ruleId]])` -Associates a message with the file for `reason` at `position`. When an -error is passed in as `reason`, copies the stack. +Create a message with `reason` at `position`. When an error is passed in as +`reason`, copies the stack. This does not add a message to `messages`. + +**Example**: + +```js +var file = new VFile(); + +file.message('Something went wrong'); +// { [1:1: Something went wrong] +// name: '1:1', +// file: '', +// reason: 'Something went wrong', +// line: null, +// column: null } +``` + +**Signatures**: -###### Parameters +* `VFileMessage = vFile.message(err|reason, node|location|position?, + ruleId?)`. -* `reason` (`string` or `Error`) - — Reason for message, uses the stack and message of the error if given -* `position` (`Node`, `Location`, or `Position`, optional) - — Place at which the message occurred in `vfile` -* `ruleId` (`string`, optional) - — Category of warning +**Parameters**: -###### Returns +* `err` (`Error`) — Original error, whose stack and message are used; -[`VFileMessage`][message]. +* `reason` (`string`) — Reason for message; + +* `node` (`Node`) — Syntax tree object; + +* `location` (`Object`) — Syntax tree location (found at `node.position`); + +* `position` (`Object`) — Syntax tree position (found at + `node.position.start` or `node.position.end`). + +* `ruleId` (`string`) — Category of warning. + +**Returns**: + +[`VFileMessage`](#vfilemessage) — File-related message with location +information. + +### `VFile#warn(reason[, position[, ruleId]])` + +Warn. Creates a non-fatal message (see [`VFile#message()`](#vfilemessagereason-position-ruleid)), +and adds it to the file's [`messages`](#vfilemessages) list. + +**Example**: + +```js +var file = new VFile(); + +file.warn('Something went wrong'); +// { [1:1: Something went wrong] +// name: '1:1', +// file: '', +// reason: 'Something went wrong', +// line: null, +// column: null, +// fatal: false } +``` + +**See**: + +* [`VFile#message`](#vfilemessagereason-position-ruleid) ### `VFile#fail(reason[, position[, ruleId]])` -Associates a fatal message with the file, then immediately throws it. -Note: fatal errors mean a file is no longer processable. -Calls [`#message()`][messages] internally. +Fail. Creates a fatal message (see `VFile#message()`), sets `fatal: true`, +adds it to the file's `messages` list. -###### Throws +If `quiet` is not `true`, throws the error. -[`VFileMessage`][message]. +**Example**: -### `VFileMessage` +```js +var file = new VFile(); + +file.fail('Something went wrong'); +// 1:1: Something went wrong +// at VFile.exception (vfile/index.js:296:11) +// at VFile.fail (vfile/index.js:360:20) +// at repl:1:6 + +file.quiet = true; +file.fail('Something went wrong'); +// { [1:1: Something went wrong] +// name: '1:1', +// file: '', +// reason: 'Something went wrong', +// line: null, +// column: null, +// fatal: true } +``` -File-related message describing something at certain position (extends -`Error`). - -###### Properties - -* `file` (`string`) — File-path (when the message was triggered) -* `reason` (`string`) — Reason for message -* `ruleId` (`string?`) — Category of message -* `source` (`string?`) — Namespace of warning -* `stack` (`string?`) — Stack of message -* `fatal` (`boolean?`) — If `true`, marks associated file as no longer - processable -* `line` (`number?`) — Starting line of error -* `column` (`number?`) — Starting column of error -* `location` (`object`) — Full range information, when available. Has - `start` and `end` properties, both set to an object with `line` and - `column`, set to `number?` +**See**: -## License +* [`VFile#message`](#vfilemessagereason-position-ruleid) + +### `VFile#hasFailed()` + +Check if a fatal message occurred making the file no longer processable. + +**Example**: -[MIT][license] © [Titus Wormer][author] +```js +var file = new VFile(); +file.quiet = true; + +file.hasFailed(); // false -<!-- Definitions --> +file.fail('Something went wrong'); +file.hasFailed(); // true +``` -[build-badge]: https://img.shields.io/travis/vfile/vfile.svg +**Signatures**: -[build-status]: https://travis-ci.org/vfile/vfile +* `boolean = vFile.hasFailed()`. -[coverage-badge]: https://img.shields.io/codecov/c/github/vfile/vfile.svg +**Returns**: -[coverage-status]: https://codecov.io/github/vfile/vfile +`boolean` — `true` if at least one of file’s `messages` has a `fatal` +property set to `true`. -[npm]: https://docs.npmjs.com/cli/install +### `VFileMessage` -[license]: LICENSE +`Error` — File-related message with location information. -[author]: http://wooorm.com +**Properties**: -[vfile]: https://cdn.rawgit.com/vfile/vfile/a20a566/logo.svg +* `name` (`string`) + — (Starting) location of the message, preceded by its file-path when + available, and joined by `':'`. Used by the native + [`Error#toString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/name); -[unified]: https://github.com/unifiedjs/unified +* `file` (`string`) — File-path; -[retext]: https://github.com/wooorm/retext +* `reason` (`string`) — Reason for message; -[remark]: https://github.com/wooorm/remark +* `line` (`number?`) — Line of error, when available; -[rehype]: https://github.com/wooorm/rehype +* `column` (`number?`) — Column of error, when available; -[vinyl]: https://github.com/gulpjs/vinyl +* `stack` (`string?`) — Stack of message, when available; -[unist]: https://github.com/syntax-tree/unist#list-of-utilities +* `fatal` (`boolean?`) — Whether the associated file is still processable. -[messages]: #vfilemessagereason-position-ruleid +* `location` (`object`) — Full range information, when available. Has + `start` and `end` properties, both set to an object with `line` and + `column`, set to `number?`. + +## License -[message]: #vfilemessage +[MIT](LICENSE) © [Titus Wormer](http://wooorm.com) |