comment-parser 1.4.1 → 1.4.2

package/CHANGELOG.md

@@ -1,63 +1,89 @@
 # v1.4.1
+
+## 1.4.2
+
+### Patch Changes
+
+- npm audit
+- ensure type, name and description on subsequent lines are properly parsed. @brettz9
+- ensure type, name and description on subsequent lines are properly parsed. @brettz9
 - fix .prettierignore
 - add source trasformation example
 
 # v1.4.0
+
 - ESM compatibility improvements; fixes #159, #161
 
 # v1.3.1
+
 - allow for valid empty jsdoc; fixes #128
 
 # v1.3.0
+
 - add support for custom block markers
 
 # v1.2.4
+
 - reverting engine constraint back to ^12.0.0
 
 # v1.2.3
+
 - publishing missing fix: point package's main to .cjs file
 
 # v1.2.2
+
 - re-export ./util on the top-level for compatibility with older Node
 - point package's main to .cjs file
 
 # v1.2.1
+
 - bump `engines` per `exports` issues in earlier Node versions
 
 # v1.2.0
+
 - keep and handle appropriately CR line endings
 
 # v1.1.6-beta.3
+
 - process CRs as a separate .lineEnd toke
 
 # v1.1.6-beta.2
+
 - ESM/CJS compatibility fixes
 
 # v1.1.6-beta.1
+
 - support native ESM
 
 # v1.1.6-beta.0
+
 - keep original CR line endings
 - allow to normalize line endings with `crlf` transform
 
 # v1.1.5
+
 - drop unused variables
 - add .editorconfig
 
 # v1.1.4
+
 - `bugfix` fix unsynced lib/
 
 # v1.1.3
+
 - export primitive type on the top level: Markers, Block, Spec, Line, Tokens, Problem
 
 # v1.1.2
+
 - `bugfix` Allow to build nested tags from `name.subname` even if `name` wasn't d
 - `bugfix` Preserve indentation when extracting comments
 
 # v1.1.1
+
 - add helpers for rewiring Spec.source <-> Spec.tags.source
 
 # v1.1.0
+
 - split tokenizers into separate modules
 - allow multiline {type} definitions - issue #109
 - allow using "=>" in [name=default] defaults – issue #112
@@ -65,75 +91,97 @@
 - add tokenizers usage example - issue #111
 
 # v1.0.0
+
 - complete rewrite in TS with more flexible API
 
 # v0.7.6
+
 - distinct non-critical errors by providing `err.warning`
 
 # 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
+
+- make stringify to start each line with \* in multiline comments
 
 # v0.7.1
+
 - ensure non-space characters after asterisk are included in source
 
 # v0.7.0
+
 - allow fenced blocks in tag description, see opts.fence
 
 # v0.6.2
+
 - document TypeScript definitions
 
 # v0.6.1
+
 - adjust strigifier indentation
 
 # v0.6.0
+
 - soft-drop node@6 support
 - migrate to ES6 syntax
 - allow to generate comments out of parsed data
 
 # v0.5.5
+
 - allow loose tag names, e.g. @.tag, @-tag
 
 # v0.5.4
+
 - allow quoted literal names, e.g. `@tag "My Var" description`
 
 # v0.5.3
+
 - corrected TypeScript definitions
 
 # v0.5.2
+
 - added TypeScript definitions
 - removed `readable-stream` dependency
 
 # v0.5.1
+
 - Support for tab as separator between tag components.
 - Docs: Indicate when `optional` is `true`; `default` property
 
 # v0.5.0
+
 - line wrapping control with `opts.join`
 
 # v0.4.2
+
 - tolerate inconsistent lines alignment within block
 
 # v0.4.1
-- refactored parsing, allow to not start lines with "* " inside block
+
+- refactored parsing, allow to not start lines with "\* " inside block
 
 # v0.3.2
+
 - fix RegExp for `description` extraction to allow $ char
 
 # v0.3.1
+
 - use `readable-stream` fro Node 0.8 comatibility
 - allow to pass optional parameters to `parse.file(path [,opts], done)`
 - allow `parse.stream` to work with Buffers in addition to strings
 
 # v0.3.0
+
 - `feature` allow to use custom parsers
 - `feature` always include source, no `raw_value` option needed
 - `bugfix` always provide `optional` tag property

package/es6/parser/tokenizers/name.js

@@ -7,9 +7,17 @@ const isQuoted = (s) => s && s.startsWith('"') && s.endsWith('"');
 export default function nameTokenizer() {
     const typeEnd = (num, { tokens }, i) => tokens.type === '' ? num : i;
     return (spec) => {
-        // look for the name in the line where {type} ends
-        const { tokens } = spec.source[spec.source.reduce(typeEnd, 0)];
-        const source = tokens.description.trimLeft();
+        // look for the name starting in the line where {type} ends
+        let finalTypeLine = spec.source.reduce(typeEnd, 0);
+        let tokens;
+        do {
+            ({ tokens } = spec.source[finalTypeLine]);
+            if (tokens.description.trim()) {
+                break;
+            }
+            finalTypeLine++;
+        } while (spec.source[finalTypeLine]);
+        const source = tokens.description.trimStart();
         const quotedGroups = source.split('"');
         // if it starts with quoted group, assume it is a literal
         if (quotedGroups.length > 1 &&

package/es6/parser/tokenizers/tag.js

@@ -15,6 +15,9 @@ export default function tagTokenizer() {
             });
             return spec;
         }
+        if (match[1].includes('/')) {
+            return spec;
+        }
         tokens.tag = match[1];
         tokens.postTag = match[3];
         tokens.description = tokens.description.slice(match[0].length);

package/es6/parser/tokenizers/type.d.ts

@@ -18,7 +18,7 @@ export type Joiner = (parts: string[]) => string;
  */
 export type Spacing = 'compact' | 'preserve' | Joiner;
 /**
- * Sets splits remaining `Spec.lines[].tokes.description` into `type` and `description`
+ * Sets splits remaining `Spec.lines[].tokens.description` into `type` and `description`
  * tokens and populates Spec.type`
  *
  * @param {Spacing} spacing tells how to deal with a whitespace

package/es6/parser/tokenizers/type.js

@@ -1,6 +1,6 @@
 import { splitSpace } from '../../util.js';
 /**
- * Sets splits remaining `Spec.lines[].tokes.description` into `type` and `description`
+ * Sets splits remaining `Spec.lines[].tokens.description` into `type` and `description`
  * tokens and populates Spec.type`
  *
  * @param {Spacing} spacing tells how to deal with a whitespace
@@ -11,10 +11,19 @@ export default function typeTokenizer(spacing = 'compact') {
     return (spec) => {
         let curlies = 0;
         let lines = [];
-        for (const [i, { tokens }] of spec.source.entries()) {
+        let descriptionBegun = false;
+        let firstTypeIteration = true;
+        for (const { tokens } of spec.source.values()) {
             let type = '';
-            if (i === 0 && tokens.description[0] !== '{')
+            if (!descriptionBegun && tokens.description.trim()) {
+                descriptionBegun = true;
+            }
+            else if (!descriptionBegun) {
+                continue;
+            }
+            if (firstTypeIteration && tokens.description[0] !== '{')
                 return spec;
+            firstTypeIteration = false;
             for (const ch of tokens.description) {
                 if (ch === '{')
                     curlies++;
@@ -28,6 +37,9 @@ export default function typeTokenizer(spacing = 'compact') {
             if (curlies === 0)
                 break;
         }
+        if (!descriptionBegun) {
+            return spec;
+        }
         if (curlies !== 0) {
             spec.problems.push({
                 code: 'spec:type:unpaired-curlies',

package/es6/primitives.js

@@ -5,4 +5,4 @@ export var Markers;
     Markers["nostart"] = "/***";
     Markers["delim"] = "*";
     Markers["end"] = "*/";
-})(Markers = Markers || (Markers = {}));
+})(Markers || (Markers = {}));

package/jest.config.cjs

@@ -1,3 +1,5 @@
+'use strict';
+
 // For a detailed explanation regarding each configuration property, visit:
 // https://jestjs.io/docs/en/configuration.html
 
@@ -6,12 +8,6 @@ const { compilerOptions: tsconfig } = JSON.parse(
 );
 
 module.exports = {
-  globals: {
-    'ts-jest': {
-      tsconfig,
-    },
-  },
-
   // All imported modules in your tests should be mocked automatically
   // automock: false,
 
@@ -186,7 +182,9 @@ module.exports = {
 
   // A map from regular expressions to paths to transformers
   transform: {
-    '^.+\\.ts$': 'ts-jest',
+    '^.+\\.ts$': ['ts-jest', {
+      tsconfig
+    }],
   },
 
   // An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "comment-parser",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "Generic JSDoc-like comment parser",
   "type": "module",
   "main": "lib/index.cjs",
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": {
       "import": "./es6/index.js",
@@ -35,14 +38,15 @@
     "test": "tests"
   },
   "devDependencies": {
-    "@types/jest": "^26.0.23",
+    "@changesets/cli": "^2.29.8",
+    "@types/jest": "^30.0.0",
     "convert-extension": "^0.3.0",
-    "jest": "^27.0.5",
-    "prettier": "2.3.1",
-    "rimraf": "^3.0.2",
-    "rollup": "^2.52.2",
-    "ts-jest": "^27.0.3",
-    "typescript": "^4.9.5"
+    "jest": "^30.1.3",
+    "prettier": "3.6.2",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.52.0",
+    "ts-jest": "^29.4.4",
+    "typescript": "^5.9.2"
   },
   "engines": {
     "node": ">= 12.0.0"
@@ -56,7 +60,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git@github.com:yavorskiy/comment-parser.git"
+    "url": "git+ssh://git@github.com/yavorskiy/comment-parser.git"
   },
   "keywords": [
     "jsdoc",
@@ -81,4 +85,4 @@
     "url": "https://github.com/syavorsky/comment-parser/issues"
   },
   "homepage": "https://github.com/syavorsky/comment-parser"
-}
+}

package/src/parser/tokenizers/name.ts

@@ -13,9 +13,19 @@ export default function nameTokenizer(): Tokenizer {
     tokens.type === '' ? num : i;
 
   return (spec: Spec): Spec => {
-    // look for the name in the line where {type} ends
-    const { tokens } = spec.source[spec.source.reduce(typeEnd, 0)];
-    const source = tokens.description.trimLeft();
+    // look for the name starting in the line where {type} ends
+    let finalTypeLine = spec.source.reduce(typeEnd, 0);
+
+    let tokens;
+    do {
+      ({ tokens } = spec.source[finalTypeLine]);
+      if (tokens.description.trim()) {
+        break;
+      }
+      finalTypeLine++;
+    } while (spec.source[finalTypeLine]);
+
+    const source = tokens.description.trimStart();
 
     const quotedGroups = source.split('"');
 

package/src/parser/tokenizers/tag.ts

@@ -20,6 +20,10 @@ export default function tagTokenizer(): Tokenizer {
       return spec;
     }
 
+    if (match[1].includes('/')) {
+      return spec;
+    }
+
     tokens.tag = match[1];
     tokens.postTag = match[3];
     tokens.description = tokens.description.slice(match[0].length);

package/src/parser/tokenizers/type.ts

@@ -23,7 +23,7 @@ export type Joiner = (parts: string[]) => string;
 export type Spacing = 'compact' | 'preserve' | Joiner;
 
 /**
- * Sets splits remaining `Spec.lines[].tokes.description` into `type` and `description`
+ * Sets splits remaining `Spec.lines[].tokens.description` into `type` and `description`
  * tokens and populates Spec.type`
  *
  * @param {Spacing} spacing tells how to deal with a whitespace
@@ -35,9 +35,18 @@ export default function typeTokenizer(spacing: Spacing = 'compact'): Tokenizer {
     let curlies = 0;
     let lines: [Tokens, string][] = [];
 
-    for (const [i, { tokens }] of spec.source.entries()) {
+    let descriptionBegun = false;
+    let firstTypeIteration = true;
+    for (const { tokens } of spec.source.values()) {
       let type = '';
-      if (i === 0 && tokens.description[0] !== '{') return spec;
+      if (!descriptionBegun && tokens.description.trim()) {
+        descriptionBegun = true;
+      } else if (!descriptionBegun) {
+        continue;
+      }
+
+      if (firstTypeIteration && tokens.description[0] !== '{') return spec;
+      firstTypeIteration = false;
 
       for (const ch of tokens.description) {
         if (ch === '{') curlies++;
@@ -50,6 +59,10 @@ export default function typeTokenizer(spacing: Spacing = 'compact'): Tokenizer {
       if (curlies === 0) break;
     }
 
+    if (!descriptionBegun) {
+      return spec;
+    }
+
     if (curlies !== 0) {
       spec.problems.push({
         code: 'spec:type:unpaired-curlies',

package/tests/unit/parser.spec.ts

@@ -167,6 +167,240 @@ test('block with tags', () => {
   ]);
 });
 
+test('tag with name and description on second line', () => {
+  const parsed = getParser()(`
+  /**
+   * @param {string}
+   *   foo The foo.
+   */`);
+  expect(parsed).toEqual([
+    {
+      description: '',
+      tags: [
+        {
+          tag: 'param',
+          name: 'foo',
+          type: 'string',
+          optional: false,
+          description: 'The foo.',
+          problems: [],
+          source: [
+            {
+              number: 2,
+              source: '   * @param {string}',
+              tokens: seedTokens({
+                start: '   ',
+                delimiter: '*',
+                postDelimiter: ' ',
+                tag: '@param',
+                postTag: ' ',
+                type: '{string}',
+              }),
+            },
+            {
+              number: 3,
+              source: '   *   foo The foo.',
+              tokens: seedTokens({
+                start: '   ',
+                delimiter: '*',
+                postDelimiter: '   ',
+                name: 'foo',
+                postName: ' ',
+                description: 'The foo.',
+              }),
+            },
+            {
+              number: 4,
+              source: '   */',
+              tokens: seedTokens({
+                start: '   ',
+                end: '*/',
+              }),
+            },
+          ],
+        },
+      ],
+      source: [
+        {
+          number: 1,
+          source: '  /**',
+          tokens: seedTokens({
+            delimiter: '/**',
+            start: '  ',
+          }),
+        },
+        {
+          number: 2,
+          source: '   * @param {string}',
+          tokens: seedTokens({
+            start: '   ',
+            delimiter: '*',
+            postDelimiter: ' ',
+            tag: '@param',
+            postTag: ' ',
+            type: '{string}',
+          }),
+        },
+        {
+          number: 3,
+          source: '   *   foo The foo.',
+          tokens: seedTokens({
+            start: '   ',
+            delimiter: '*',
+            postDelimiter: '   ',
+            name: 'foo',
+            postName: ' ',
+            description: 'The foo.',
+          }),
+        },
+        {
+          number: 4,
+          source: '   */',
+          tokens: seedTokens({
+            start: '   ',
+            end: '*/',
+          }),
+        },
+      ],
+      problems: [],
+    },
+  ]);
+});
+
+test('tag with type, name and description on subsequent lines', () => {
+  const parsed = getParser()(`
+  /**
+   * @param
+   * {string}
+   *   foo
+   * The foo.
+   */`);
+  expect(parsed).toEqual([
+    {
+      description: '',
+      tags: [
+        {
+          tag: 'param',
+          name: 'foo',
+          type: 'string',
+          optional: false,
+          description: 'The foo.',
+          problems: [],
+          source: [
+            {
+              number: 2,
+              source: '   * @param',
+              tokens: seedTokens({
+                start: '   ',
+                delimiter: '*',
+                postDelimiter: ' ',
+                tag: '@param',
+              }),
+            },
+            {
+              number: 3,
+              source: '   * {string}',
+              tokens: seedTokens({
+                start: '   ',
+                delimiter: '*',
+                postDelimiter: ' ',
+                type: '{string}',
+              }),
+            },
+            {
+              number: 4,
+              source: '   *   foo',
+              tokens: seedTokens({
+                start: '   ',
+                delimiter: '*',
+                postDelimiter: '   ',
+                name: 'foo',
+              }),
+            },
+            {
+              number: 5,
+              source: '   * The foo.',
+              tokens: seedTokens({
+                start: '   ',
+                delimiter: '*',
+                postDelimiter: ' ',
+                description: 'The foo.',
+              }),
+            },
+            {
+              number: 6,
+              source: '   */',
+              tokens: seedTokens({
+                start: '   ',
+                end: '*/',
+              }),
+            },
+          ],
+        },
+      ],
+      source: [
+        {
+          number: 1,
+          source: '  /**',
+          tokens: seedTokens({
+            delimiter: '/**',
+            start: '  ',
+          }),
+        },
+        {
+          number: 2,
+          source: '   * @param',
+          tokens: seedTokens({
+            start: '   ',
+            delimiter: '*',
+            postDelimiter: ' ',
+            tag: '@param',
+          }),
+        },
+        {
+          number: 3,
+          source: '   * {string}',
+          tokens: seedTokens({
+            start: '   ',
+            delimiter: '*',
+            postDelimiter: ' ',
+            type: '{string}',
+          }),
+        },
+        {
+          number: 4,
+          source: '   *   foo',
+          tokens: seedTokens({
+            start: '   ',
+            delimiter: '*',
+            postDelimiter: '   ',
+            name: 'foo',
+          }),
+        },
+        {
+          number: 5,
+          source: '   * The foo.',
+          tokens: seedTokens({
+            start: '   ',
+            delimiter: '*',
+            postDelimiter: ' ',
+            description: 'The foo.',
+          }),
+        },
+        {
+          number: 6,
+          source: '   */',
+          tokens: seedTokens({
+            start: '   ',
+            end: '*/',
+          }),
+        },
+      ],
+      problems: [],
+    },
+  ]);
+});
+
 test('no source cloning', () => {
   const parsed = getParser()(`
   /**