babel-extract-comments - npm Package Compare versions

Comparing version 0.1.0 to 1.0.0

index.js

 /*!
  * babel-extract-comments <https://github.com/jonschlinkert/babel-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,2 +10,6 @@
 
+const fs = require('fs');
+const path = require('path');
+const babylon = require('babylon');
+
 /**
@@ -16,31 +20,46 @@ * Extract code comments from the given `string`.
  * var extract = require('babel-extract-comments');
- * extract('// this is a code comment');
+ * console.log(extract('// this is a code comment'));
+ * // [{ type: 'CommentBlock',
+ * //  value: '!\n * babel-extract-comments <https://github.com/jonschlinkert/babel-extract-comments>\n *\n *
+ * // Copyright (c) 2014-2018, Jon Schlinkert.\n * Released under the MIT License.\n ',
+ * //   start: 0,
+ * //   end: 173,
+ * //   loc: SourceLocation { start: [Position], end: [Position] } }]
  * ```
  * @param  {String} `string` String of javascript
- * @param  {Function} `fn` Optional. Functionto transform commend objects (AST tokens)
- * @return {Object} Object of code comments.
+ * @return {Array} Array of code comment objects.
  * @api public
  */
 
-module.exports = function(str, fn) {
-  var babel = require('babel-core');
-  var res = babel.transform(str, {
-    ast: true,
-    comments: true,
-    code: false
-  });
+function extract(str, options) {
+  const res = babylon.parse(str, options);
+  return res.comments;
+}
 
-  var comments = res.ast.comments;
-  var len = comments.length, i = -1;
-  while (++i < len) {
-    var comment = comments[i];
-    comment.range = [comment.start, comment.end];
-    if (typeof fn === 'function') {
-      var obj = fn(comment);
-      if (obj) {
-        comment = obj;
-      }
-    }
-  }
-  return 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);
 };
+
+/**
+ * Expose `extract`
+ */
+
+module.exports = extract;

package.json

 {
   "name": "babel-extract-comments",
-  "description": "Uses babel to extract JavaScript code comments from a string. Returns an array of comment objects, with line, column, index, comment type and comment string.",
-  "version": "0.1.0",
+  "description": "Uses babel (babylon) to extract JavaScript code comments from a JavaScript string or file.",
+  "version": "1.0.0",
   "homepage": "https://github.com/jonschlinkert/babel-extract-comments",
@@ -17,3 +17,3 @@ "author": "Jon Schlinkert (https://github.com/jonschlinkert)",
   "engines": {
-    "node": ">=0.8"
+    "node": ">=4"
   },
@@ -24,8 +24,10 @@ "scripts": {
   "dependencies": {
-    "babel-core": "^6.3.26"
+    "babylon": "^6.18.0"
   },
   "devDependencies": {
-    "gulp-format-md": "^0.1.4"
+    "gulp-format-md": "^1.0.0",
+    "mocha": "^3.5.3"
   },
   "keywords": [
+    "babel",
     "block",
@@ -36,3 +38,2 @@ "code",
     "context",
-    "babel",
     "extract",
@@ -44,2 +45,10 @@ "glob",
   "verb": {
+    "toc": false,
+    "layout": "default",
+    "tasks": [
+      "readme"
+    ],
+    "plugins": [
+      "gulp-format-md"
+    ],
     "related": {
@@ -53,7 +62,6 @@ "list": [
     },
-    "plugins": [
-      "gulp-format-md"
-    ],
-    "layout": "default"
+    "lint": {
+      "reflinks": true
+    }
   }
 }

README.md

@@ -1,17 +0,7 @@
-# babel-extract-comments [![NPM version](https://img.shields.io/npm/v/babel-extract-comments.svg)](https://www.npmjs.com/package/babel-extract-comments) [![Build Status](https://img.shields.io/travis/jonschlinkert/babel-extract-comments.svg)](https://travis-ci.org/jonschlinkert/babel-extract-comments)
+# babel-extract-comments [![NPM version](https://img.shields.io/npm/v/babel-extract-comments.svg?style=flat)](https://www.npmjs.com/package/babel-extract-comments) [![NPM monthly downloads](https://img.shields.io/npm/dm/babel-extract-comments.svg?style=flat)](https://npmjs.org/package/babel-extract-comments) [![NPM total downloads](https://img.shields.io/npm/dt/babel-extract-comments.svg?style=flat)](https://npmjs.org/package/babel-extract-comments) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/babel-extract-comments.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/babel-extract-comments)
 
-> Uses babel to extract JavaScript code comments from a string. Returns an array of comment objects, with line, column, index, comment type and comment string.
+> Uses babel (babylon) to extract JavaScript code comments from a JavaScript string or file.
 
-- [Install](#install)
-- [API](#api)
-  * [Transform function](#transform-function)
-- [Example results](#example-results)
-- [Related projects](#related-projects)
-- [Running tests](#running-tests)
-- [Contributing](#contributing)
-- [Author](#author)
-- [License](#license)
+Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
 
-_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_
-
 ## Install
@@ -22,12 +12,23 @@
 ```sh
-$ npm i babel-extract-comments --save
+$ npm install --save babel-extract-comments
 ```
 
+## Usage
+
+Add to your Node.js/JavaScript project with the following line of code:
+
+```js
+const extract = require('babel-extract-comments');
+```
+
 ## API
 
+### [extract](index.js#L32)
+
+Extract code comments from the given `string`.
+
 **Params**
 
 * `string` **{String}**: String of javascript
-* `fn` **{Function}**: Optional. Functionto transform commend objects (AST tokens)
-* `returns` **{Object}**: Object of code comments.
+* `returns` **{Array}**: Array of code comment objects.
 
@@ -38,64 +39,95 @@ **Example**
 var extract = require('babel-extract-comments');
-extract('// this is a code comment');
+console.log(extract('// this is a code comment'));
+// [{ type: 'CommentBlock',
+//  value: '!\n * babel-extract-comments <https://github.com/jonschlinkert/babel-extract-comments>\n *\n *
+// Copyright (c) 2014-2018, Jon Schlinkert.\n * Released under the MIT License.\n ',
+//   start: 0,
+//   end: 173,
+//   loc: SourceLocation { start: [Position], end: [Position] } }]
 ```
 
-### Transform function
+### [.file](index.js#L53)
 
-Optionally pass a function as the second argument to transform comment objects.
+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
-var comments = extract(javascriptString, function(comment) {
-  comment.foo = 'bar';
-});
-console.log(comments[0].foo);
-//=> 'bar';
+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 } } } ]
 ```
 
-## Example results
+## About
 
-See [fixtures/app.js](./fixtures/app.js) to see the code comments used to generate the following:
+<details>
+<summary><strong>Contributing</strong></summary>
 
-```js
-[{ type: 'Block',
-  value: '*\n * Create an instance of App with `options`.\n *\n * @param {Object} options\n * @api public\n ',
-  range: [ 15, 112 ],
-  loc: { 
-    start: { line: 3, column: 0 }, 
-    end: { line: 8, column: 3 } } 
-}]
+Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
+
+</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 install && npm test
 ```
 
-## Related projects
+</details>
 
-* [esprima-extract-comments](https://www.npmjs.com/package/esprima-extract-comments): Extract code comments from string or from a glob of files using esprima. | [homepage](https://github.com/jonschlinkert/esprima-extract-comments)
-* [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://www.npmjs.com/package/extract-comments) | [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>Building docs</strong></summary>
 
-## Running tests
+_(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.)_
 
-Install dev dependencies:
+To generate the readme, run the following command:
 
 ```sh
-$ npm i -d && npm test
+$ npm install -g verbose/verb#dev verb-generate-readme && verb
 ```
 
-## Contributing
+</details>
 
-Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/babel-extract-comments/issues/new).
+### Related projects
 
-## Author
+You might also be interested in these projects:
 
+* [esprima-extract-comments](https://www.npmjs.com/package/esprima-extract-comments): Extract code comments from string or from a glob of files using esprima. | [homepage](https://github.com/jonschlinkert/esprima-extract-comments "Extract code comments from string or from a glob of files using esprima.")
+* [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.")
+
+### Contributors
+
+| **Commits** | **Contributor** | 
+| --- | --- |
+| 4 | [jonschlinkert](https://github.com/jonschlinkert) |
+| 1 | [eventualbuddha](https://github.com/eventualbuddha) |
+
+### 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

9394

increased by38.45%

Lines of code

55

increased by37.5%

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

131

increased by32.32%

Worsened metrics

Dev dependency count

2

increased by100%

Number of low supply chain risk alerts

2

increased by100%

Dependency changes

• + Addedbabylon@^6.18.0

• - Removedbabel-core@^6.3.26

• - Removedansi-regex@2.1.1(transitive)

• - Removedansi-styles@2.2.1(transitive)

• - Removedbabel-code-frame@6.26.0(transitive)

• - Removedbabel-core@6.26.3(transitive)

• - Removedbabel-generator@6.26.1(transitive)

• - Removedbabel-helpers@6.24.1(transitive)

• - Removedbabel-messages@6.23.0(transitive)

• - Removedbabel-register@6.26.0(transitive)

• - Removedbabel-runtime@6.26.0(transitive)

• - Removedbabel-template@6.26.0(transitive)

• - Removedbabel-traverse@6.26.0(transitive)

• - Removedbabel-types@6.26.0(transitive)

• - Removedbalanced-match@1.0.2(transitive)

• - Removedbrace-expansion@1.1.11(transitive)

• - Removedchalk@1.1.3(transitive)

• - Removedconcat-map@0.0.1(transitive)

• - Removedconvert-source-map@1.9.0(transitive)

• - Removedcore-js@2.6.12(transitive)

• - Removeddebug@2.6.9(transitive)

• - Removeddetect-indent@4.0.0(transitive)

• - Removedescape-string-regexp@1.0.5(transitive)

• - Removedesutils@2.0.3(transitive)

• - Removedglobals@9.18.0(transitive)

• - Removedhas-ansi@2.0.0(transitive)

• - Removedhome-or-tmp@2.0.0(transitive)

• - Removedinvariant@2.2.4(transitive)

• - Removedis-finite@1.1.0(transitive)

• - Removedjs-tokens@3.0.2(transitive)

• - Removedjsesc@1.3.0(transitive)

• - Removedjson5@0.5.1(transitive)

• - Removedlodash@4.17.21(transitive)

• - Removedloose-envify@1.4.0(transitive)

• - Removedminimatch@3.1.2(transitive)

• - Removedminimist@1.2.8(transitive)

• - Removedmkdirp@0.5.6(transitive)

• - Removedms@2.0.0(transitive)

• - Removedos-homedir@1.0.2(transitive)

• - Removedos-tmpdir@1.0.2(transitive)

• - Removedpath-is-absolute@1.0.1(transitive)

• - Removedprivate@0.1.8(transitive)

• - Removedregenerator-runtime@0.11.1(transitive)

• - Removedrepeating@2.0.1(transitive)

• - Removedslash@1.0.0(transitive)

• - Removedsource-map@0.5.7(transitive)

• - Removedsource-map-support@0.4.18(transitive)

• - Removedstrip-ansi@3.0.1(transitive)

• - Removedsupports-color@2.0.0(transitive)

• - Removedto-fast-properties@1.0.3(transitive)

• - Removedtrim-right@1.0.1(transitive)