esprima-extract-comments - npm Package Compare versions

Comparing version 0.2.1 to 1.0.0

index.js

 /*!
  * esprima-extract-comments <https://github.com/jonschlinkert/esprima-extract-comments>
  *
- * Copyright (c) 2014 Jon Schlinkert, contributors.
- * Licensed under the MIT license.
+ * Copyright (c) 2014-2018, Jon Schlinkert.
+ * Released under the MIT License.
  */
@@ -10,27 +10,62 @@
 
-var esprima = require('esprima');
+const fs = require('fs');
+const path = require('path');
+const esprima = require('esprima');
 
 /**
- * Extract code comments from the given `string`.
+ * Extract line and block comments from a string of JavaScript.
  *
  * ```js
- * var extract = require('esprima-extract-comments');
- * extract('// this is a code comment');
+ * console.log(extract('// this is a line comment'));
+ * // [ { type: 'Line',
+ * //     value: ' this is a line comment',
+ * //     range: [ 0, 25 ],
+ * //     loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 25 } } } ]
  * ```
  * @param  {String} `string`
- * @param  {Object} `options` Options to pass to esprima.
- * @return {Object} Object of code comments.
+ * @param  {Object} `options` Options to pass to [esprima][].
+ * @return {Array} Array of code comment objects.
  * @api public
  */
 
-module.exports = function(str) {
-  var ast = esprima.parse(str, {
-    tolerant: true,
-    comment: true,
-    tokens: true,
-    range: true,
-    loc: true
-  });
+function extract(str, options) {
+  const defaults = { tolerant: true, comment: true, tokens: true, range: true, loc: true };
+  const tokens = esprima.tokenize(str, Object.assign({}, defaults, options));
+  return tokens.filter(isComment);
+}
 
-  return ast.comments;
+/**
+ * Extract code comments from a JavaScript file.
+ *
+ * ```js
+ * console.log(extract.file('some-file.js'), { cwd: 'some/path' });
+ * // [ { type: 'Line',
+ * //     value: ' this is a line comment',
+ * //     range: [ 0, 25 ],
+ * //     loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 25 } } } ]
+ * ```
+ * @param  {String} `file` Filepath to the file to parse.
+ * @param  {Object} `options` Options to pass to [esprima][].
+ * @return {Array} Array of code comment objects.
+ * @api public
+ */
+
+extract.file = function(file, options) {
+  const opts = Object.assign({ cwd: process.cwd() }, options);
+  const str = fs.readFileSync(path.resolve(opts.cwd, file), 'utf8');
+  return extract(str, options);
 };
+
+/**
+ * Returns true if `token` is a valid comment token
+ */
+
+function isComment(token) {
+  return token.type === 'LineComment' || token.type === 'BlockComment';
+}
+
+/**
+ * Expose `extract`
+ */
+
+module.exports = extract;

package.json

 {
   "name": "esprima-extract-comments",
   "description": "Extract code comments from string or from a glob of files using esprima.",
-  "version": "0.2.1",
+  "version": "1.0.0",
   "homepage": "https://github.com/jonschlinkert/esprima-extract-comments",
@@ -17,3 +17,3 @@ "author": "Jon Schlinkert (https://github.com/jonschlinkert)",
   "engines": {
-    "node": ">=0.8"
+    "node": ">=4"
   },
@@ -24,4 +24,8 @@ "scripts": {
   "dependencies": {
-    "esprima": "^2.7.1"
+    "esprima": "^4.0.0"
   },
+  "devDependencies": {
+    "gulp-format-md": "^1.0.0",
+    "mocha": "^3.5.3"
+  },
   "keywords": [
@@ -40,2 +44,10 @@ "block",
   "verb": {
+    "toc": false,
+    "layout": "default",
+    "tasks": [
+      "readme"
+    ],
+    "plugins": [
+      "gulp-format-md"
+    ],
     "related": {
@@ -48,6 +60,6 @@ "list": [
     },
-    "plugins": [
-      "gulp-format-md"
-    ]
+    "lint": {
+      "reflinks": true
+    }
   }
 }

README.md

@@ -1,5 +0,7 @@
-# esprima-extract-comments [![NPM version](https://img.shields.io/npm/v/esprima-extract-comments.svg)](https://www.npmjs.com/package/esprima-extract-comments) [![Build Status](https://img.shields.io/travis/jonschlinkert/esprima-extract-comments.svg)](https://travis-ci.org/jonschlinkert/esprima-extract-comments)
+# esprima-extract-comments [![NPM version](https://img.shields.io/npm/v/esprima-extract-comments.svg?style=flat)](https://www.npmjs.com/package/esprima-extract-comments) [![NPM monthly downloads](https://img.shields.io/npm/dm/esprima-extract-comments.svg?style=flat)](https://npmjs.org/package/esprima-extract-comments) [![NPM total downloads](https://img.shields.io/npm/dt/esprima-extract-comments.svg?style=flat)](https://npmjs.org/package/esprima-extract-comments) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/esprima-extract-comments.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/esprima-extract-comments)
 
 > Extract code comments from string or from a glob of files using esprima.
 
+Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
+
 ## Install
@@ -10,12 +12,29 @@
 ```sh
-$ npm i esprima-extract-comments --save
+$ npm install --save esprima-extract-comments
 ```
 
+## Breaking changes in v1.0.0!
+
+* line `comment.type` was changed from `line` to `LineComment`
+* block `comment.type` was changed from `block` to `BlockComment`
+
+## Usage
+
+Add to your Node.js/JavaScript project with the following line of code:
+
+```js
+const extract = require('esprima-extract-comments');
+```
+
 ## API
 
+### [extract](index.js#L30)
+
+Extract line and block comments from a string of JavaScript.
+
 **Params**
 
 * `string` **{String}**
-* `options` **{Object}**: Options to pass to esprima.
-* `returns` **{Object}**: Object of code comments.
+* `options` **{Object}**: Options to pass to [esprima](http://esprima.org).
+* `returns` **{Array}**: Array of code comment objects.
 
@@ -25,80 +44,85 @@ **Example**
 ```js
-var extract = require('esprima-extract-comments');
-extract('// this is a code comment');
+console.log(extract('// this is a line comment'));
+// [ { type: 'Line',
+//     value: ' this is a line comment',
+//     range: [ 0, 25 ],
+//     loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 25 } } } ]
 ```
 
-## Example results
+### [.file](index.js#L52)
 
-See [fixtures/app.js](./fixtures/app.js) to see the code comments used to generate the following:
+Extract code comments from a JavaScript file.
 
+**Params**
+
+* `file` **{String}**: Filepath to the file to parse.
+* `options` **{Object}**: Options to pass to [esprima](http://esprima.org).
+* `returns` **{Array}**: Array of code comment objects.
+
+**Example**
+
 ```js
-[{
-  type: 'Block',
-  value: '*\n * Create an instance of App with `options`
-    .\n *\n * @param {Object} options\n * @api public\n ',
-  loc: {
-    start: {line: 3, column: 0 },
-    end: {line: 8, column: 3 }
-  }
-}, {
-  type: 'Block',
-  value: '*\n * Set `key` on cache with the given `value`
-    \n *\n * @param {String} `key`\n * @param {any} 
-    `value`\n * @api public\n ',
-  loc: {
-    start: {line: 15, column: 0 },
-    end: {line: 21, column: 3 }
-  }
-}, {
-  type: 'Block',
-  value: '*\n * Get `key` from cache.\n *\n * @param 
-    {String} `key`\n * @api public\n ',
-  loc: {
-    start: {line: 25, column: 0 },
-    end: {line: 30, column: 3 }
-  }
-}, {
-  type: 'Block',
-  value: '*\n * Delete `key` from cache\n *\n * 
-    @param {String} `key`\n * @param {any} value\n * 
-    @api public\n ',
-  loc: {
-    start: {line: 34, column: 0 },
-    end: {line: 40, column: 3 }
-  }
-}]
+console.log(extract.file('some-file.js'), { cwd: 'some/path' });
+// [ { type: 'Line',
+//     value: ' this is a line comment',
+//     range: [ 0, 25 ],
+//     loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 25 } } } ]
 ```
 
-## Related projects
+## About
 
-* [extract-comments](https://www.npmjs.com/package/extract-comments): Extract code comments from string or from a glob of files. | [homepage](https://github.com/jonschlinkert/extract-comments)
-* [js-comments](https://www.npmjs.com/package/js-comments): Parse JavaScript code comments and generate API documentation. | [homepage](https://github.com/jonschlinkert/js-comments)
-* [parse-comments](https://www.npmjs.com/package/parse-comments): Parse code comments from JavaScript or any language that uses the same format. | [homepage](https://github.com/jonschlinkert/parse-comments)
+<details>
+<summary><strong>Contributing</strong></summary>
 
-## Running tests
+Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
 
-Install dev dependencies:
+</details>
 
+<details>
+<summary><strong>Running Tests</strong></summary>
+
+Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
+
 ```sh
-$ npm i -d && npm test
+$ npm install && npm test
 ```
 
-## Contributing
+</details>
 
-Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/esprima-extract-comments/issues/new).
+<details>
+<summary><strong>Building docs</strong></summary>
 
-## Author
+_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
 
+To generate the readme, run the following command:
+
+```sh
+$ npm install -g verbose/verb#dev verb-generate-readme && verb
+```
+
+</details>
+
+### Related projects
+
+You might also be interested in these projects:
+
+* [extract-comments](https://www.npmjs.com/package/extract-comments): Uses esprima to extract line and block comments from a string of JavaScript. Also optionally… [more](https://github.com/jonschlinkert/extract-comments) | [homepage](https://github.com/jonschlinkert/extract-comments "Uses esprima to extract line and block comments from a string of JavaScript. Also optionally parses code context (the next line of code after a comment).")
+* [js-comments](https://www.npmjs.com/package/js-comments): Parse JavaScript code comments and generate API documentation. | [homepage](https://github.com/jonschlinkert/js-comments "Parse JavaScript code comments and generate API documentation.")
+* [parse-comments](https://www.npmjs.com/package/parse-comments): Parse code comments from JavaScript or any language that uses the same format. | [homepage](https://github.com/jonschlinkert/parse-comments "Parse code comments from JavaScript or any language that uses the same format.")
+
+### Author
+
 **Jon Schlinkert**
 
+* [linkedin/in/jonschlinkert](https://linkedin.com/in/jonschlinkert)
 * [github/jonschlinkert](https://github.com/jonschlinkert)
-* [twitter/jonschlinkert](http://twitter.com/jonschlinkert)
+* [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
 
-## License
+### License
 
-Copyright © 2015 [Jon Schlinkert](https://github.com/jonschlinkert)
-Released under the MIT license.
+Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
+Released under the [MIT License](LICENSE).
 
 ***
 
-_This file was generated by [verb](https://github.com/verbose/verb) on December 30, 2015._
+_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on February 12, 2018._

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

9045

increased by54.77%

Lines of code

60

increased by100%

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

126

increased by23.53%

Worsened metrics

Dev dependency count

2

increased byInfinity%

Number of low supply chain risk alerts

2

increased by100%

Dependency changes

• + Addedesprima@4.0.1(transitive)

• - Removedesprima@2.7.3(transitive)

• Updatedesprima@^4.0.0