comment-parser 1.4.0 → 1.4.2

package/CHANGELOG.md

@@ -1,59 +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
@@ -61,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.0",
+  "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/e2e/examples.js

@@ -192,6 +192,46 @@ function parse_advanced_parsing(source, parse, _, _, tokenizers) {
     .join('\n');
 }
 
+function stringify_rename(source, parse, stringify, transforms) {
+  // You can do any manipulations with the parsed result
+  // See how each block is being mapped. If you are updating a Block.source
+  // then rewireSource(block) should be called on each changed block.
+  // If changes were made to Block.tags[].source then call rewireSpecs(block).
+  // This example shows how you can "rename" @param tags: value1 -> value11, value2 -> value22
+
+  /**
+   * Description may go
+   * over multiple lines followed by @tags
+   * @param {string} name the name parameter
+   * @param {any} value1 first value parameter
+   *   with a multipline description
+   * @param {any} value2 second value parameter
+   */
+
+  function renameParam(from, to) {
+    return (block) => {
+      for (const tag of block.tags) {
+        if (tag.tag === 'param' && tag.name === from) {
+          tag.name = to;
+          for (const line of tag.source) {
+            if (line.tokens.name === from) line.tokens.name = to;
+          }
+        }
+      }
+      return block;
+    };
+  }
+
+  const transform = transforms.flow(
+    renameParam('value1', 'value11'),
+    renameParam('value2', 'value22'),
+    stringify
+  );
+
+  const parsed = parse(source);
+  const stringified = parsed.map(transform);
+}
+
 (typeof window === 'undefined' ? module.exports : window).examples = [
   parse_defaults,
   parse_line_numbering,
@@ -200,4 +240,5 @@ function parse_advanced_parsing(source, parse, _, _, tokenizers) {
   parse_source_exploration,
   parse_advanced_parsing,
   stringify_formatting,
+  stringify_rename,
 ];