├── .editorconfig ├── .eslintrc.json ├── .gitattributes ├── .gitignore ├── .travis.yml ├── .verb.md ├── LICENSE ├── README.md ├── index.js ├── package.json └── test ├── fixtures ├── angular.js └── app.js └── test.js /.editorconfig: -------------------------------------------------------------------------------- 1 | # http://editorconfig.org/ 2 | root = true 3 | 4 | [*] 5 | charset = utf-8 6 | end_of_line = lf 7 | indent_size = 2 8 | indent_style = space 9 | insert_final_newline = true 10 | trim_trailing_whitespace = true 11 | 12 | [{**/{actual,fixtures,expected,templates}/**,*.md}] 13 | trim_trailing_whitespace = false 14 | insert_final_newline = false 15 | -------------------------------------------------------------------------------- /.eslintrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": [ 3 | "eslint:recommended" 4 | ], 5 | 6 | "env": { 7 | "browser": false, 8 | "es6": true, 9 | "node": true, 10 | "mocha": true 11 | }, 12 | 13 | "parserOptions":{ 14 | "ecmaVersion": 9, 15 | "sourceType": "module", 16 | "ecmaFeatures": { 17 | "modules": true, 18 | "experimentalObjectRestSpread": true 19 | } 20 | }, 21 | 22 | "globals": { 23 | "document": false, 24 | "navigator": false, 25 | "window": false 26 | }, 27 | 28 | "rules": { 29 | "accessor-pairs": 2, 30 | "arrow-spacing": [2, { "before": true, "after": true }], 31 | "block-spacing": [2, "always"], 32 | "brace-style": [2, "1tbs", { "allowSingleLine": true }], 33 | "comma-dangle": [2, "never"], 34 | "comma-spacing": [2, { "before": false, "after": true }], 35 | "comma-style": [2, "last"], 36 | "constructor-super": 2, 37 | "curly": [2, "multi-line"], 38 | "dot-location": [2, "property"], 39 | "eol-last": 2, 40 | "eqeqeq": [2, "allow-null"], 41 | "generator-star-spacing": [2, { "before": true, "after": true }], 42 | "handle-callback-err": [2, "^(err|error)$" ], 43 | "indent": [2, 2, { "SwitchCase": 1 }], 44 | "key-spacing": [2, { "beforeColon": false, "afterColon": true }], 45 | "keyword-spacing": [2, { "before": true, "after": true }], 46 | "new-cap": [2, { "newIsCap": true, "capIsNew": false }], 47 | "new-parens": 2, 48 | "no-array-constructor": 2, 49 | "no-caller": 2, 50 | "no-class-assign": 2, 51 | "no-cond-assign": 2, 52 | "no-const-assign": 2, 53 | "no-control-regex": 2, 54 | "no-debugger": 2, 55 | "no-delete-var": 2, 56 | "no-dupe-args": 2, 57 | "no-dupe-class-members": 2, 58 | "no-dupe-keys": 2, 59 | "no-duplicate-case": 2, 60 | "no-empty-character-class": 2, 61 | "no-eval": 2, 62 | "no-ex-assign": 2, 63 | "no-extend-native": 2, 64 | "no-extra-bind": 2, 65 | "no-extra-boolean-cast": 2, 66 | "no-extra-parens": [2, "functions"], 67 | "no-fallthrough": 2, 68 | "no-floating-decimal": 2, 69 | "no-func-assign": 2, 70 | "no-implied-eval": 2, 71 | "no-inner-declarations": [2, "functions"], 72 | "no-invalid-regexp": 2, 73 | "no-irregular-whitespace": 2, 74 | "no-iterator": 2, 75 | "no-label-var": 2, 76 | "no-labels": 2, 77 | "no-lone-blocks": 2, 78 | "no-mixed-spaces-and-tabs": 2, 79 | "no-multi-spaces": 2, 80 | "no-multi-str": 2, 81 | "no-multiple-empty-lines": [2, { "max": 1 }], 82 | "no-native-reassign": 0, 83 | "no-negated-in-lhs": 2, 84 | "no-new": 2, 85 | "no-new-func": 2, 86 | "no-new-object": 2, 87 | "no-new-require": 2, 88 | "no-new-wrappers": 2, 89 | "no-obj-calls": 2, 90 | "no-octal": 2, 91 | "no-octal-escape": 2, 92 | "no-proto": 0, 93 | "no-redeclare": 2, 94 | "no-regex-spaces": 2, 95 | "no-return-assign": 2, 96 | "no-self-compare": 2, 97 | "no-sequences": 2, 98 | "no-shadow-restricted-names": 2, 99 | "no-spaced-func": 2, 100 | "no-sparse-arrays": 2, 101 | "no-this-before-super": 2, 102 | "no-throw-literal": 2, 103 | "no-trailing-spaces": 0, 104 | "no-undef": 2, 105 | "no-undef-init": 2, 106 | "no-unexpected-multiline": 2, 107 | "no-unneeded-ternary": [2, { "defaultAssignment": false }], 108 | "no-unreachable": 2, 109 | "no-unused-vars": [2, { "vars": "all", "args": "none" }], 110 | "no-useless-call": 0, 111 | "no-with": 2, 112 | "one-var": [0, { "initialized": "never" }], 113 | "operator-linebreak": [0, "after", { "overrides": { "?": "before", ":": "before" } }], 114 | "padded-blocks": [0, "never"], 115 | "quotes": [2, "single", "avoid-escape"], 116 | "radix": 2, 117 | "semi": [2, "always"], 118 | "semi-spacing": [2, { "before": false, "after": true }], 119 | "space-before-blocks": [2, "always"], 120 | "space-before-function-paren": [2, "never"], 121 | "space-in-parens": [2, "never"], 122 | "space-infix-ops": 2, 123 | "space-unary-ops": [2, { "words": true, "nonwords": false }], 124 | "spaced-comment": [0, "always", { "markers": ["global", "globals", "eslint", "eslint-disable", "*package", "!", ","] }], 125 | "use-isnan": 2, 126 | "valid-typeof": 2, 127 | "wrap-iife": [2, "any"], 128 | "yoda": [2, "never"] 129 | } 130 | } 131 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Enforce Unix newlines 2 | *.* text eol=lf 3 | *.css text eol=lf 4 | *.html text eol=lf 5 | *.js text eol=lf 6 | *.json text eol=lf 7 | *.less text eol=lf 8 | *.md text eol=lf 9 | *.yml text eol=lf 10 | 11 | *.jpg binary 12 | *.gif binary 13 | *.png binary 14 | *.jpeg binary -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # always ignore files 2 | *.DS_Store 3 | .idea 4 | .vscode 5 | *.sublime-* 6 | 7 | # test related, or directories generated by tests 8 | test/actual 9 | actual 10 | coverage 11 | .nyc* 12 | 13 | # npm 14 | node_modules 15 | npm-debug.log 16 | 17 | # yarn 18 | yarn.lock 19 | yarn-error.log 20 | 21 | # misc 22 | _gh_pages 23 | _draft 24 | _drafts 25 | bower_components 26 | vendor 27 | temp 28 | tmp 29 | TODO.md 30 | package-lock.json -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | sudo: false 2 | os: 3 | - linux 4 | - osx 5 | language: node_js 6 | node_js: 7 | - node 8 | - '9' 9 | - '8' 10 | - '7' 11 | - '6' 12 | - '5' 13 | - '4' 14 | -------------------------------------------------------------------------------- /.verb.md: -------------------------------------------------------------------------------- 1 | ## Usage 2 | 3 | Add to your Node.js/JavaScript project with the following line of code: 4 | 5 | ```js 6 | const extract = require('babel-extract-comments'); 7 | ``` 8 | 9 | ## API 10 | {%= apidocs('index.js') %} 11 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015, 2018, Jon Schlinkert. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in 13 | all copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | THE SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 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) 2 | 3 | > Uses babel (babylon) to extract JavaScript code comments from a JavaScript string or file. 4 | 5 | Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support. 6 | 7 | ## Install 8 | 9 | Install with [npm](https://www.npmjs.com/): 10 | 11 | ```sh 12 | $ npm install --save babel-extract-comments 13 | ``` 14 | 15 | ## Usage 16 | 17 | Add to your Node.js/JavaScript project with the following line of code: 18 | 19 | ```js 20 | const extract = require('babel-extract-comments'); 21 | ``` 22 | 23 | ## API 24 | 25 | ### [extract](index.js#L32) 26 | 27 | Extract code comments from the given `string`. 28 | 29 | **Params** 30 | 31 | * `string` **{String}**: String of javascript 32 | * `returns` **{Array}**: Array of code comment objects. 33 | 34 | **Example** 35 | 36 | ```js 37 | var extract = require('babel-extract-comments'); 38 | console.log(extract('// this is a code comment')); 39 | // [{ type: 'CommentBlock', 40 | // value: '!\n * babel-extract-comments \n *\n * 41 | // Copyright (c) 2014-2018, Jon Schlinkert.\n * Released under the MIT License.\n ', 42 | // start: 0, 43 | // end: 173, 44 | // loc: SourceLocation { start: [Position], end: [Position] } }] 45 | ``` 46 | 47 | ### [.file](index.js#L53) 48 | 49 | Extract code comments from a JavaScript file. 50 | 51 | **Params** 52 | 53 | * `file` **{String}**: Filepath to the file to parse. 54 | * `options` **{Object}**: Options to pass to [esprima](http://esprima.org). 55 | * `returns` **{Array}**: Array of code comment objects. 56 | 57 | **Example** 58 | 59 | ```js 60 | console.log(extract.file('some-file.js'), { cwd: 'some/path' }); 61 | // [ { type: 'Line', 62 | // value: ' this is a line comment', 63 | // range: [ 0, 25 ], 64 | // loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 25 } } } ] 65 | ``` 66 | 67 | ## About 68 | 69 |
70 | Contributing 71 | 72 | Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). 73 | 74 |
75 | 76 |
77 | Running Tests 78 | 79 | 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: 80 | 81 | ```sh 82 | $ npm install && npm test 83 | ``` 84 | 85 |
86 | 87 |
88 | Building docs 89 | 90 | _(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.)_ 91 | 92 | To generate the readme, run the following command: 93 | 94 | ```sh 95 | $ npm install -g verbose/verb#dev verb-generate-readme && verb 96 | ``` 97 | 98 |
99 | 100 | ### Related projects 101 | 102 | You might also be interested in these projects: 103 | 104 | * [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.") 105 | * [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).") 106 | * [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.") 107 | * [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.") 108 | 109 | ### Contributors 110 | 111 | | **Commits** | **Contributor** | 112 | | --- | --- | 113 | | 4 | [jonschlinkert](https://github.com/jonschlinkert) | 114 | | 1 | [eventualbuddha](https://github.com/eventualbuddha) | 115 | 116 | ### Author 117 | 118 | **Jon Schlinkert** 119 | 120 | * [linkedin/in/jonschlinkert](https://linkedin.com/in/jonschlinkert) 121 | * [github/jonschlinkert](https://github.com/jonschlinkert) 122 | * [twitter/jonschlinkert](https://twitter.com/jonschlinkert) 123 | 124 | ### License 125 | 126 | Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert). 127 | Released under the [MIT License](LICENSE). 128 | 129 | *** 130 | 131 | _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on February 12, 2018._ -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | /*! 2 | * babel-extract-comments 3 | * 4 | * Copyright (c) 2014-2018, Jon Schlinkert. 5 | * Released under the MIT License. 6 | */ 7 | 8 | 'use strict'; 9 | 10 | const fs = require('fs'); 11 | const path = require('path'); 12 | const babylon = require('babylon'); 13 | 14 | /** 15 | * Extract code comments from the given `string`. 16 | * 17 | * ```js 18 | * var extract = require('babel-extract-comments'); 19 | * console.log(extract('// this is a code comment')); 20 | * // [{ type: 'CommentBlock', 21 | * // value: '!\n * babel-extract-comments \n *\n * 22 | * // Copyright (c) 2014-2018, Jon Schlinkert.\n * Released under the MIT License.\n ', 23 | * // start: 0, 24 | * // end: 173, 25 | * // loc: SourceLocation { start: [Position], end: [Position] } }] 26 | * ``` 27 | * @param {String} `string` String of javascript 28 | * @return {Array} Array of code comment objects. 29 | * @api public 30 | */ 31 | 32 | function extract(str, options) { 33 | const res = babylon.parse(str, options); 34 | return res.comments; 35 | } 36 | 37 | /** 38 | * Extract code comments from a JavaScript file. 39 | * 40 | * ```js 41 | * console.log(extract.file('some-file.js'), { cwd: 'some/path' }); 42 | * // [ { type: 'Line', 43 | * // value: ' this is a line comment', 44 | * // range: [ 0, 25 ], 45 | * // loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 25 } } } ] 46 | * ``` 47 | * @param {String} `file` Filepath to the file to parse. 48 | * @param {Object} `options` Options to pass to [esprima][]. 49 | * @return {Array} Array of code comment objects. 50 | * @api public 51 | */ 52 | 53 | extract.file = function(file, options) { 54 | const opts = Object.assign({ cwd: process.cwd() }, options); 55 | const str = fs.readFileSync(path.resolve(opts.cwd, file), 'utf8'); 56 | return extract(str, options); 57 | }; 58 | 59 | /** 60 | * Expose `extract` 61 | */ 62 | 63 | module.exports = extract; 64 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "babel-extract-comments", 3 | "description": "Uses babel (babylon) to extract JavaScript code comments from a JavaScript string or file.", 4 | "version": "1.0.0", 5 | "homepage": "https://github.com/jonschlinkert/babel-extract-comments", 6 | "author": "Jon Schlinkert (https://github.com/jonschlinkert)", 7 | "repository": "jonschlinkert/babel-extract-comments", 8 | "bugs": { 9 | "url": "https://github.com/jonschlinkert/babel-extract-comments/issues" 10 | }, 11 | "license": "MIT", 12 | "files": [ 13 | "index.js" 14 | ], 15 | "main": "index.js", 16 | "engines": { 17 | "node": ">=4" 18 | }, 19 | "scripts": { 20 | "test": "mocha" 21 | }, 22 | "dependencies": { 23 | "babylon": "^6.18.0" 24 | }, 25 | "devDependencies": { 26 | "gulp-format-md": "^1.0.0", 27 | "mocha": "^3.5.3" 28 | }, 29 | "keywords": [ 30 | "babel", 31 | "block", 32 | "code", 33 | "comment", 34 | "comments", 35 | "context", 36 | "extract", 37 | "glob", 38 | "javascript", 39 | "parse" 40 | ], 41 | "verb": { 42 | "toc": false, 43 | "layout": "default", 44 | "tasks": [ 45 | "readme" 46 | ], 47 | "plugins": [ 48 | "gulp-format-md" 49 | ], 50 | "related": { 51 | "list": [ 52 | "esprima-extract-comments", 53 | "extract-comments", 54 | "js-comments", 55 | "parse-comments" 56 | ] 57 | }, 58 | "lint": { 59 | "reflinks": true 60 | } 61 | } 62 | } 63 | -------------------------------------------------------------------------------- /test/fixtures/app.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | /** 4 | * Create an instance of App with `options`. 5 | * 6 | * @param {Object} options 7 | * @api public 8 | */ 9 | 10 | function App(options) { 11 | this.options = options || {}; 12 | this.cache = {}; 13 | } 14 | 15 | /** 16 | * Set `key` on cache with the given `value` 17 | * 18 | * @param {String} `key` 19 | * @param {any} `value` 20 | * @api public 21 | */ 22 | 23 | // this is a line comment 24 | App.prototype.set = function(key, value) {}; 25 | 26 | /** 27 | * Get `key` from cache. 28 | * 29 | * @param {String} `key` 30 | * @api public 31 | */ 32 | 33 | App.prototype.get = function(key) {}; 34 | 35 | /** 36 | * Delete `key` from cache 37 | * 38 | * @param {String} `key` 39 | * @param {any} value 40 | * @api public 41 | */ 42 | 43 | App.prototype.del = function(key) {}; 44 | -------------------------------------------------------------------------------- /test/test.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const fs = require('fs'); 4 | const path = require('path'); 5 | const util = require('util'); 6 | const assert = require('assert'); 7 | const extract = require('..'); 8 | const read = name => fs.readFileSync(path.join(__dirname, `fixtures/${name}`), 'utf8'); 9 | 10 | function isBlock(c) { 11 | return c.type === 'CommentBlock'; 12 | } 13 | function isLine(c) { 14 | return c.type === 'CommentLine'; 15 | } 16 | 17 | describe('babel-extract-comments', function() { 18 | describe('main export', function() { 19 | it('should extract line comments', function() { 20 | const comments = extract('foo // bar'); 21 | assert(Array.isArray(comments)); 22 | assert.equal(comments.filter(isLine).length, 1); 23 | assert.equal(comments.filter(isLine)[0].value, ' bar'); 24 | }); 25 | 26 | it('should extract block comments', function() { 27 | const comments = extract(read('app.js')); 28 | assert(comments.filter(isBlock).length > 1); 29 | }); 30 | 31 | it('should extract line and block comments', function() { 32 | const str = fs.readFileSync(path.join(__dirname, '../index.js'), 'utf8'); 33 | const comments = extract(str); 34 | assert(Array.isArray(comments)); 35 | assert(comments.length >= 1); 36 | assert(/babel-extract-comments/.test(comments[0].value)); 37 | }); 38 | 39 | it('should extract complex comments', function() { 40 | const comments = extract(read('angular.js'), { allowReturnOutsideFunction: true }); 41 | assert.equal(comments[comments.length - 1].loc.start.line, 29702); 42 | }); 43 | }); 44 | 45 | describe('.file', function() { 46 | it('should extract block comments from a file', function() { 47 | const comments = extract.file('app.js', { cwd: path.join(__dirname, 'fixtures') }); 48 | assert(comments.filter(isBlock).length > 1); 49 | }); 50 | 51 | it('should extract line comments from a file', function() { 52 | const comments = extract.file('app.js', { cwd: path.join(__dirname, 'fixtures') }); 53 | assert(comments.filter(isLine).length >= 1); 54 | }); 55 | }); 56 | }); 57 | 58 | --------------------------------------------------------------------------------