comment-parser 0.7.1 → 0.7.5

package/.editorconfig

@@ -0,0 +1,12 @@
+# This file is for unifying the coding style for different editors and IDEs
+# editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_size = 2

package/.vscode/launch.json

@@ -0,0 +1,18 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Test this",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "program": "${workspaceFolder}/node_modules/.bin/mocha",
+      "args": ["${file}"]
+    }
+  ]
+}

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# v0.7.5
+- name parsing fixes
+
+# v0.7.4
+- node 8 backward compatibility fixes
+
+# v0.7.3
+- make stringify result more close to the source
+
+# v0.7.2
+- make stringify to start each line with * in multiline comments
+
 # v0.7.1
 - ensure non-space characters after asterisk are included in source
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-parser",
-  "version": "0.7.1",
+  "version": "0.7.5",
   "description": "Generic JSDoc-like comment parser. ",
   "main": "index.js",
   "types": "index.d.ts",
@@ -10,15 +10,17 @@
   "dependencies": {},
   "devDependencies": {
     "chai": "^4.2.0",
-    "eslint": "^6.6.0",
-    "eslint-config-standard": "^14.1.0",
-    "eslint-plugin-import": "^2.18.2",
-    "eslint-plugin-node": "^10.0.0",
+    "eslint": "^6.8.0",
+    "eslint-config-standard": "^14.1.1",
+    "eslint-plugin-import": "^2.20.2",
+    "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-promise": "^4.2.1",
     "eslint-plugin-standard": "^4.0.1",
-    "mocha": "^6.2.2",
-    "nodemon": "^1.19.4",
-    "typescript": "^3.6.4"
+    "mocha": "^7.1.2",
+    "nodemon": "^2.0.3",
+    "nyc": "^15.0.1",
+    "readable-stream": "^3.6.0",
+    "typescript": "^3.8.3"
   },
   "engines": {
     "node": ">= 6.0.0"
@@ -28,10 +30,19 @@
     "lint:fix": "eslint --fix .",
     "test:lint": "eslint .",
     "test:typescript": "tsc index.d.ts",
-    "test:unit": "mocha tests",
+    "test:unit": "nyc mocha tests",
     "test": "npm run test:typescript && npm run test:lint && npm run test:unit",
     "watch": "nodemon -q -i node_modules -x npm test"
   },
+  "nyc": {
+    "branches": 85,
+    "lines": 85,
+    "functions": 85,
+    "statements": 85,
+    "exclude": [
+      "tests"
+    ]
+  },
   "repository": {
     "type": "git",
     "url": "git@github.com:yavorskiy/comment-parser.git"
@@ -50,7 +61,8 @@
     "Evgeny Reznichenko (https://github.com/zxcabs)",
     "Javier \"Ciberma\" Mora (https://github.com/jhm-ciberman)",
     "Jordan Harband (https://github.com/ljharb)",
-    "tengattack (https://github.com/tengattack)"
+    "tengattack (https://github.com/tengattack)",
+    "Jayden Seric (https://github.com/jaydenseric)"
   ],
   "license": "MIT",
   "bugs": {

package/parser.js

@@ -33,8 +33,6 @@ function find (list, filter) {
  * @returns {object} parsed tag node
  */
 function parse_tag (str, parsers) {
-  if (typeof str !== 'string' || str[0] !== '@') { return null }
-
   const data = parsers.reduce(function (state, parser) {
     let result
 
@@ -140,8 +138,6 @@ function parse_block (source, opts) {
   const tags = source.reduce(function (tags, tag) {
     const tag_node = parse_tag(tag.source, opts.parsers)
 
-    if (!tag_node) { return tags }
-
     tag_node.line = tag.line
     tag_node.source = tag.source
 

package/parsers.js

@@ -13,13 +13,12 @@ function skipws (str) {
 const PARSERS = {}
 
 PARSERS.parse_tag = function parse_tag (str) {
-  const result = str.match(/^\s*@(\S+)/)
-
-  if (!result) { throw new Error('Invalid `@tag`, missing @ symbol') }
+  const match = str.match(/^\s*@(\S+)/)
+  if (!match) { throw new SyntaxError('Invalid `@tag`, missing @ symbol') }
 
   return {
-    source: result[0],
-    data: { tag: result[1] }
+    source: match[0],
+    data: { tag: match[1] }
   }
 }
 
@@ -39,7 +38,7 @@ PARSERS.parse_type = function parse_type (str, data) {
     if (curlies === 0) { break }
   }
 
-  if (curlies !== 0) { throw new Error('Invalid `{type}`, unpaired curlies') }
+  if (curlies !== 0) { throw new SyntaxError('Invalid `{type}`, unpaired curlies') }
 
   return {
     source: str.slice(0, pos),
@@ -69,19 +68,22 @@ PARSERS.parse_name = function parse_name (str, data) {
       if (brackets === 0 && /\s/.test(str[pos])) { break }
     }
 
-    if (brackets !== 0) { throw new Error('Invalid `name`, unpaired brackets') }
+    if (brackets !== 0) { throw new SyntaxError('Invalid `name`, unpaired brackets') }
 
-    res = { name: name, optional: false }
+    res = { name, optional: false }
 
     if (name[0] === '[' && name[name.length - 1] === ']') {
       res.optional = true
       name = name.slice(1, -1)
 
-      if (name.indexOf('=') !== -1) {
-        const parts = name.split('=')
-        name = parts[0]
-        res.default = parts[1].replace(/^(["'])(.+)(\1)$/, '$2')
-      }
+      const match = name.match(
+        /^\s*([^=]+?)(?:\s*=\s*(.+?))?\s*(?=$)/
+      )
+
+      if (!match) throw new SyntaxError('Invalid `name`, bad syntax')
+
+      name = match[1]
+      if (match[2]) res.default = match[2]
     }
   }
 
@@ -96,12 +98,12 @@ PARSERS.parse_name = function parse_name (str, data) {
 PARSERS.parse_description = function parse_description (str, data) {
   if (data.errors && data.errors.length) { return null }
 
-  const result = str.match(/^\s+((.|\s)+)?/)
+  const match = str.match(/^\s+((.|\s)+)?/)
 
-  if (result) {
+  if (match) {
     return {
-      source: result[0],
-      data: { description: result[1] === undefined ? '' : result[1] }
+      source: match[0],
+      data: { description: match[1] === undefined ? '' : match[1] }
     }
   }
 

package/stringifier.js

@@ -33,10 +33,16 @@ const stringifyBlock = exports.stringifyBlock = function stringifyBlock (
 ) {
   // block.line
   const indnt = getIndent(indent)
-  return (block.description ? `${indnt}* ${block.description}\n${indnt}*\n` : '') +
-    block.tags.reduce((s, tag) => {
-      return s + stringifyTag(tag, { indent })
-    }, '')
+
+  return (
+    block.description
+      ? block.description.replace(/^\n/, '').replace(/^(.*)\n?/gm, (n0, descLine) => {
+        return `${indnt}*${descLine ? ` ${descLine}` : ''}\n`
+      })
+      : ''
+  ) + block.tags.reduce((s, tag) => {
+    return s + stringifyTag(tag, { indent })
+  }, '')
 }
 
 const stringifyTag = exports.stringifyTag = function stringifyTag (
@@ -46,11 +52,12 @@ const stringifyTag = exports.stringifyTag = function stringifyTag (
   const {
     type, name, optional, description, tag: tagName, default: deflt //, line , source
   } = tag
+
   return indnt + `* @${tagName}` +
     (type ? ` {${type}}` : '') +
-    (name ? ` ${
+    (name.trim() ? ` ${
       optional ? '[' : ''
-    }${name}${deflt ? `=${deflt}` : ''}${
+    }${name.trimRight()}${deflt ? `=${deflt}` : ''}${
       optional ? ']' : ''
     }` : '') +
     (description ? ` ${description.replace(/\n/g, '\n' + indnt + '* ')}` : '') + '\n'

package/.travis.yml

@@ -1,10 +0,0 @@
-language: node_js
-node_js:
-  - 12
-  - 10
-  - 8
-branches:
-  except:
-    - /^v\d+\.\d+\.\d+$/
-git:
-  depth: 1

package/tests/custom-parsers.spec.js

@@ -1,132 +0,0 @@
-/* eslint no-unused-vars:off */
-'use strict'
-
-const { expect } = require('chai')
-const parse = require('./parse')
-
-describe('parse() with custom tag parsers', function () {
-  function sample () {
-    /**
-     * @tag {type} name description
-     */
-    var a
-  }
-
-  it('should use `opts.parsers`', function () {
-    const parsers = [
-      function everything (str) {
-        return {
-          source: str,
-          data: {
-            tag: 'tag',
-            type: 'type',
-            name: 'name',
-            optional: false,
-            description: 'description'
-          }
-        }
-      }
-    ]
-
-    expect(parse(sample, { parsers: parsers })[0])
-      .to.eql({
-        line: 1,
-        description: '',
-        source: '@tag {type} name description',
-        tags: [{
-          tag: 'tag',
-          type: 'type',
-          name: 'name',
-          description: 'description',
-          optional: false,
-          source: '@tag {type} name description',
-          line: 2
-        }]
-      })
-  })
-
-  it('should merge parsers result', function () {
-    const parsers = [
-      function parser1 (str) {
-        return {
-          source: '',
-          data: { tag: 'tag' }
-        }
-      },
-      function parser2 (str) {
-        return {
-          source: '',
-          data: { type: 'type' }
-        }
-      },
-      function parser3 (str) {
-        return {
-          source: '',
-          data: {
-            name: 'name',
-            description: 'description'
-          }
-        }
-      }
-    ]
-
-    expect(parse(sample, { parsers: parsers })[0])
-      .to.eql({
-        line: 1,
-        description: '',
-        source: '@tag {type} name description',
-        tags: [{
-          tag: 'tag',
-          type: 'type',
-          name: 'name',
-          description: 'description',
-          optional: false,
-          source: '@tag {type} name description',
-          line: 2
-        }]
-      })
-  })
-
-  it('should catch parser exceptions and populate `errors` field', function () {
-    const parsers = [
-      function parser1 (str) {
-        return {
-          source: '',
-          data: { tag: 'tag' }
-        }
-      },
-      function parser2 (str) {
-        throw new Error('error 1')
-      },
-      function parser3 (str) {
-        throw new Error('error 2')
-      },
-      function parser4 (str) {
-        return {
-          source: '',
-          data: { name: 'name' }
-        }
-      }
-    ]
-
-    expect(parse(sample, { parsers: parsers })[0])
-      .to.eql({
-        line: 1,
-        description: '',
-        source: '@tag {type} name description',
-        tags: [{
-          tag: 'tag',
-          type: '',
-          name: 'name',
-          description: '',
-          optional: false,
-          source: '@tag {type} name description',
-          errors: [
-            'parser2: error 1',
-            'parser3: error 2'
-          ],
-          line: 2
-        }]
-      })
-  })
-})

package/tests/files.spec.js

@@ -1,69 +0,0 @@
-/* eslint no-unused-vars:off */
-'use strict'
-
-const fs = require('fs')
-const path = require('path')
-const stream = require('readable-stream')
-const { expect } = require('chai')
-const parse = require('../index')
-
-describe('File parsing', function () {
-  it('should parse the file by path', function (done) {
-    parse.file(path.resolve(__dirname, 'fixtures/sample.js'), function (err, parsed) {
-      if (err) { done(err) }
-
-      expect(parsed)
-        .to.be.an('array')
-
-      expect(parsed.length)
-        .to.eq(4)
-
-      expect(parsed[0].description)
-        .to.eq('File description')
-
-      expect(parsed[1].tags[0].tag)
-        .to.eq('class')
-
-      expect(parsed[2].tags[0].tag)
-        .to.eq('property')
-
-      expect(parsed[3].tags[0].tag)
-        .to.eq('method')
-
-      done()
-    })
-  })
-
-  it('should path the error if file dows not exist', function (done) {
-    parse.file('does/not/exists', function (err, parsed) {
-      expect(err)
-        .to.be.instanceof(Error)
-      done()
-    })
-  })
-
-  it('should return `Transform` stream', function (done) {
-    let count = 0
-
-    const readable = fs.createReadStream(path.resolve(__dirname, 'fixtures/sample.js'), { encoding: 'utf8' })
-
-    const writable = new stream.Writable({ objectMode: true })
-    writable._write = function (data, encoding, done) {
-      count++
-      done()
-    }
-
-    readable
-      .on('error', done)
-      .pipe(parse.stream())
-      .on('error', done)
-      .pipe(writable)
-      .on('error', done)
-      .on('finish', function () {
-        expect(count)
-          .to.eq(4)
-
-        done()
-      })
-  })
-})

package/tests/fixtures/sample.js

@@ -1,36 +0,0 @@
-
-/**
- * File description
- */
-
-/**
- * Sample class
- * @class Point
- * @param {Object} [coords]
- * @param {Int} coords.x
- * @param {Int} coords.y
- */
-function Point (options) {
-
-}
-
-/*
- * This should be skipped
- */
-
-/**
- * Tells if point was ever initilized with coordinates
- * @property {Boolean} [initilized=false]
- */
-Point.prototype.initilized = false
-
-/**
- * Moves point by x,y
- * @method move
- * @param {Object} [by]
- * @param {Int} by.x
- * @param {Int} by.y
- */
-Point.prototype.move = function (by) {
-
-}

package/tests/parse.js

@@ -1,20 +0,0 @@
-/**
- * Source lines numeration:
- *
- * 0 function() {
- * 1  // source with comments
- * 2 }
- *
- */
-
-'use strict'
-
-const parse = require('../index')
-
-module.exports = function (func, opts) {
-  let str = func.toString()
-  str = str
-    .slice(str.indexOf('{') + 1, str.lastIndexOf('}'))
-    .replace(/\r\n/g, '\n')
-  return parse(str, opts)
-}