comment-parser 1.3.1 → 1.4.1

package/lib/util.d.ts

@@ -1,4 +1,4 @@
-import { Block, Tokens, Spec } from './primitives';
+import { Block, Tokens, Spec } from './primitives.js';
 export declare function isSpace(source: string): boolean;
 export declare function hasCR(source: string): boolean;
 export declare function splitCR(source: string): [string, string];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-parser",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "Generic JSDoc-like comment parser",
   "type": "module",
   "main": "lib/index.cjs",
@@ -39,17 +39,16 @@
     "convert-extension": "^0.3.0",
     "jest": "^27.0.5",
     "prettier": "2.3.1",
-    "replace": "^1.2.1",
     "rimraf": "^3.0.2",
     "rollup": "^2.52.2",
     "ts-jest": "^27.0.3",
-    "typescript": "^4.3.4"
+    "typescript": "^4.9.5"
   },
   "engines": {
     "node": ">= 12.0.0"
   },
   "scripts": {
-    "build": "rimraf lib es6 browser; tsc -p tsconfig.json && tsc -p tsconfig.node.json && rollup -o browser/index.js -f iife --context window -n CommentParser es6/index.js && convert-extension cjs lib/ && cd es6 && replace \"from '(\\.[^']*)'\" \"from '\\$1.js'\" * -r --include=\"*.js\"",
+    "build": "rimraf lib es6 browser; tsc -p tsconfig.json && tsc -p tsconfig.node.json && rollup -o browser/index.js -f iife --context window -n CommentParser es6/index.js && convert-extension cjs lib/",
     "format": "prettier --write src tests",
     "pretest": "rimraf coverage; npm run build",
     "test": "prettier --check src tests && jest --verbose",

package/src/index.ts

@@ -1,23 +1,23 @@
-import getParser, { Options as ParserOptions } from './parser/index';
-import descriptionTokenizer from './parser/tokenizers/description';
-import nameTokenizer from './parser/tokenizers/name';
-import tagTokenizer from './parser/tokenizers/tag';
-import typeTokenizer from './parser/tokenizers/type';
-import getStringifier from './stringifier/index';
-import alignTransform from './transforms/align';
-import indentTransform from './transforms/indent';
-import crlfTransform from './transforms/crlf';
-import { flow as flowTransform } from './transforms/index';
-import { rewireSpecs, rewireSource, seedBlock, seedTokens } from './util';
+import getParser, { Options as ParserOptions } from './parser/index.js';
+import descriptionTokenizer from './parser/tokenizers/description.js';
+import nameTokenizer from './parser/tokenizers/name.js';
+import tagTokenizer from './parser/tokenizers/tag.js';
+import typeTokenizer from './parser/tokenizers/type.js';
+import getStringifier from './stringifier/index.js';
+import alignTransform from './transforms/align.js';
+import indentTransform from './transforms/indent.js';
+import crlfTransform from './transforms/crlf.js';
+import { flow as flowTransform } from './transforms/index.js';
+import { rewireSpecs, rewireSource, seedBlock, seedTokens } from './util.js';
 
-export * from './primitives';
+export * from './primitives.js';
 
 export function parse(source: string, options: Partial<ParserOptions> = {}) {
   return getParser(options)(source);
 }
 
 export const stringify = getStringifier();
-export { default as inspect } from './stringifier/inspect';
+export { default as inspect } from './stringifier/inspect.js';
 
 export const transforms = {
   flow: flowTransform,

package/src/parser/block-parser.ts

@@ -1,4 +1,4 @@
-import { Line } from '../primitives';
+import { Line } from '../primitives.js';
 
 const reTag = /^@\S+/;
 

package/src/parser/index.ts

@@ -1,15 +1,15 @@
-import { Block, Line, Problem, BlockMarkers, Markers } from '../primitives';
-import { splitLines } from '../util';
-import blockParser from './block-parser';
-import sourceParser from './source-parser';
-import specParser from './spec-parser';
-import { Tokenizer } from './tokenizers/index';
-import tokenizeTag from './tokenizers/tag';
-import tokenizeType from './tokenizers/type';
-import tokenizeName from './tokenizers/name';
+import { Block, Line, Problem, BlockMarkers, Markers } from '../primitives.js';
+import { splitLines } from '../util.js';
+import blockParser from './block-parser.js';
+import sourceParser from './source-parser.js';
+import specParser from './spec-parser.js';
+import { Tokenizer } from './tokenizers/index.js';
+import tokenizeTag from './tokenizers/tag.js';
+import tokenizeType from './tokenizers/type.js';
+import tokenizeName from './tokenizers/name.js';
 import tokenizeDescription, {
   getJoiner as getDescriptionJoiner,
-} from './tokenizers/description';
+} from './tokenizers/description.js';
 
 export interface Options {
   // start count for source line numbers

package/src/parser/source-parser.ts

@@ -1,5 +1,5 @@
-import { Line, Tokens, BlockMarkers, Markers } from '../primitives';
-import { seedTokens, splitSpace, splitCR } from '../util';
+import { Line, Tokens, BlockMarkers, Markers } from '../primitives.js';
+import { seedTokens, splitSpace, splitCR } from '../util.js';
 
 export interface Options {
   startLine: number;

package/src/parser/spec-parser.ts

@@ -1,6 +1,6 @@
-import { Line, Spec } from '../primitives';
-import { seedSpec } from '../util';
-import { Tokenizer } from './tokenizers/index';
+import { Line, Spec } from '../primitives.js';
+import { seedSpec } from '../util.js';
+import { Tokenizer } from './tokenizers/index.js';
 
 export type Parser = (source: Line[]) => Spec;
 

package/src/parser/tokenizers/description.ts

@@ -1,5 +1,5 @@
-import { Spec, Line, BlockMarkers, Markers } from '../../primitives';
-import { Tokenizer } from './index';
+import { Spec, Line, BlockMarkers, Markers } from '../../primitives.js';
+import { Tokenizer } from './index.js';
 
 /**
  * Walks over provided lines joining description token into a single string.

package/src/parser/tokenizers/index.ts

@@ -1,4 +1,4 @@
-import { Spec } from '../../primitives';
+import { Spec } from '../../primitives.js';
 
 /**
  * Splits `spect.lines[].token.description` into other tokens,

package/src/parser/tokenizers/name.ts

@@ -1,6 +1,6 @@
-import { Spec, Line } from '../../primitives';
-import { splitSpace, isSpace } from '../../util';
-import { Tokenizer } from './index';
+import { Spec, Line } from '../../primitives.js';
+import { splitSpace, isSpace } from '../../util.js';
+import { Tokenizer } from './index.js';
 
 const isQuoted = (s: string) => s && s.startsWith('"') && s.endsWith('"');
 

package/src/parser/tokenizers/tag.ts

@@ -1,5 +1,5 @@
-import { Spec } from '../../primitives';
-import { Tokenizer } from './index';
+import { Spec } from '../../primitives.js';
+import { Tokenizer } from './index.js';
 
 /**
  * Splits the `@prefix` from remaining `Spec.lines[].token.description` into the `tag` token,

package/src/parser/tokenizers/type.ts

@@ -1,6 +1,6 @@
-import { Spec, Tokens } from '../../primitives';
-import { splitSpace } from '../../util';
-import { Tokenizer } from './index';
+import { Spec, Tokens } from '../../primitives.js';
+import { splitSpace } from '../../util.js';
+import { Tokenizer } from './index.js';
 
 /**
  * Joiner is a function taking collected type token string parts,

package/src/stringifier/index.ts

@@ -1,4 +1,4 @@
-import { Block, Tokens } from '../primitives';
+import { Block, Tokens } from '../primitives.js';
 
 export type Stringifier = (block: Block) => string;
 

package/src/stringifier/inspect.ts

@@ -1,5 +1,5 @@
-import { Block, Tokens } from '../primitives';
-import { isSpace } from '../util';
+import { Block, Tokens } from '../primitives.js';
+import { isSpace } from '../util.js';
 
 interface Width {
   line: number;

package/src/transforms/align.ts

@@ -1,6 +1,6 @@
-import { Transform } from './index';
-import { BlockMarkers, Block, Line, Markers } from '../primitives';
-import { rewireSource } from '../util';
+import { Transform } from './index.js';
+import { BlockMarkers, Block, Line, Markers } from '../primitives.js';
+import { rewireSource } from '../util.js';
 
 interface Width {
   start: number;

package/src/transforms/crlf.ts

@@ -1,6 +1,6 @@
-import { Transform } from './index';
-import { Block, Line } from '../primitives';
-import { rewireSource } from '../util';
+import { Transform } from './index.js';
+import { Block, Line } from '../primitives.js';
+import { rewireSource } from '../util.js';
 
 const order = [
   'end',

package/src/transforms/indent.ts

@@ -1,6 +1,6 @@
-import { Transform } from './index';
-import { Block, Line } from '../primitives';
-import { rewireSource } from '../util';
+import { Transform } from './index.js';
+import { Block, Line } from '../primitives.js';
+import { rewireSource } from '../util.js';
 
 const pull = (offset: number) => (str) => str.slice(offset);
 const push = (offset: number) => {

package/src/transforms/index.ts

@@ -1,4 +1,4 @@
-import { Block } from '../primitives';
+import { Block } from '../primitives.js';
 
 export type Transform = (Block: Block) => Block;
 

package/src/util.ts

@@ -1,4 +1,4 @@
-import { Block, Tokens, Spec, Line } from './primitives';
+import { Block, Tokens, Spec, Line } from './primitives.js';
 
 export function isSpace(source: string): boolean {
   return /^\s+$/.test(source);

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,
 ];

package/tests/unit/block-parser.spec.ts

@@ -1,6 +1,6 @@
-import getParser from '../../src/parser/block-parser';
-import { Line } from '../../src/primitives';
-import { seedTokens } from '../../src/util';
+import getParser from '../../src/parser/block-parser.js';
+import { Line } from '../../src/primitives.js';
+import { seedTokens } from '../../src/util.js';
 
 let source: Line[];
 

package/tests/unit/inspect.spec.ts

@@ -1,6 +1,6 @@
-import getParser from '../../src/parser/index';
-import inspect from '../../src/stringifier/inspect';
-import { seedBlock } from '../../src/util';
+import getParser from '../../src/parser/index.js';
+import inspect from '../../src/stringifier/inspect.js';
+import { seedBlock } from '../../src/util.js';
 
 test('multiple lines', () => {
   const source = `

package/tests/unit/parser.spec.ts

@@ -1,5 +1,5 @@
-import getParser from '../../src/parser';
-import { seedTokens } from '../../src/util';
+import getParser from '../../src/parser/index.js';
+import { seedTokens } from '../../src/util.js';
 
 test('block with tags', () => {
   const parsed = getParser()(`

package/tests/unit/source-parser.spec.ts

@@ -1,6 +1,6 @@
-import getParser, { Parser } from '../../src/parser/source-parser';
-import { Line } from '../../src/primitives';
-import { splitLines, seedBlock, seedTokens } from '../../src/util';
+import getParser, { Parser } from '../../src/parser/source-parser.js';
+import { Line } from '../../src/primitives.js';
+import { splitLines, seedBlock, seedTokens } from '../../src/util.js';
 
 let _parse: Parser;
 

package/tests/unit/spacer-description-joiner.spec.ts

@@ -1,6 +1,6 @@
-import { getJoiner } from '../../src/parser/tokenizers/description';
-import { Line } from '../../src/primitives';
-import { seedTokens } from '../../src/util';
+import { getJoiner } from '../../src/parser/tokenizers/description.js';
+import { Line } from '../../src/primitives.js';
+import { seedTokens } from '../../src/util.js';
 
 const source: Line[] = [
   {

package/tests/unit/spec-description-tokenizer.spec.ts

@@ -1,5 +1,5 @@
-import descriptionTokenizer from '../../src/parser/tokenizers/description';
-import { seedSpec, seedTokens } from '../../src/util';
+import descriptionTokenizer from '../../src/parser/tokenizers/description.js';
+import { seedSpec, seedTokens } from '../../src/util.js';
 
 const sourceSingle = [
   {

package/tests/unit/spec-name-tokenizer.spec.ts

@@ -1,5 +1,5 @@
-import nameTokenizer from '../../src/parser/tokenizers/name';
-import { seedTokens, seedSpec } from '../../src/util';
+import nameTokenizer from '../../src/parser/tokenizers/name.js';
+import { seedTokens, seedSpec } from '../../src/util.js';
 
 const tokenize = nameTokenizer();
 

package/tests/unit/spec-parser.spec.ts

@@ -1,10 +1,10 @@
-import descriptionTokenizer from '../../src/parser/tokenizers/description';
-import nameTokenizer from '../../src/parser/tokenizers/name';
-import tagTokenizer from '../../src/parser/tokenizers/tag';
-import typeTokenizer from '../../src/parser/tokenizers/type';
-import getParser from '../../src/parser/spec-parser';
-import { seedTokens, seedSpec } from '../../src/util';
-import { Spec, Problem } from '../../src/primitives';
+import descriptionTokenizer from '../../src/parser/tokenizers/description.js';
+import nameTokenizer from '../../src/parser/tokenizers/name.js';
+import tagTokenizer from '../../src/parser/tokenizers/tag.js';
+import typeTokenizer from '../../src/parser/tokenizers/type.js';
+import getParser from '../../src/parser/spec-parser.js';
+import { seedTokens, seedSpec } from '../../src/util.js';
+import { Spec, Problem } from '../../src/primitives.js';
 
 const parse = getParser({
   tokenizers: [

package/tests/unit/spec-tag-tokenizer.spec.ts

@@ -1,5 +1,5 @@
-import tagTokenizer from '../../src/parser/tokenizers/tag';
-import { seedTokens, seedSpec } from '../../src/util';
+import tagTokenizer from '../../src/parser/tokenizers/tag.js';
+import { seedTokens, seedSpec } from '../../src/util.js';
 
 const tokenize = tagTokenizer();
 

package/tests/unit/spec-type-tokenizer.spec.ts

@@ -1,5 +1,5 @@
-import typeTokenizer, { Joiner } from '../../src/parser/tokenizers/type';
-import { seedTokens, seedSpec } from '../../src/util';
+import typeTokenizer, { Joiner } from '../../src/parser/tokenizers/type.js';
+import { seedTokens, seedSpec } from '../../src/util.js';
 
 const tokenize = typeTokenizer();
 

package/tests/unit/stringifier.spec.ts

@@ -1,4 +1,4 @@
-import getStringifier from '../../src/stringifier';
+import getStringifier from '../../src/stringifier/index.js';
 
 const source = [
   {

package/tests/unit/transforms-align.spec.ts

@@ -1,6 +1,6 @@
-import align from '../../src/transforms/align';
-import getParser, { Parser } from '../../src/parser/index';
-import getStringifier, { Stringifier } from '../../src/stringifier/index';
+import align from '../../src/transforms/align.js';
+import getParser, { Parser } from '../../src/parser/index.js';
+import getStringifier, { Stringifier } from '../../src/stringifier/index.js';
 
 let parse: Parser;
 let stringify: Stringifier;

package/tests/unit/transforms-crlf.spec.ts

@@ -1,6 +1,6 @@
-import crlf, { Ending } from '../../src/transforms/crlf';
-import getParser, { Parser } from '../../src/parser/index';
-import getStringifier, { Stringifier } from '../../src/stringifier/index';
+import crlf, { Ending } from '../../src/transforms/crlf.js';
+import getParser, { Parser } from '../../src/parser/index.js';
+import getStringifier, { Stringifier } from '../../src/stringifier/index.js';
 
 const tests = [
   [

package/tests/unit/transforms-indent.spec.ts

@@ -1,6 +1,6 @@
-import indent from '../../src/transforms/indent';
-import getParser from '../../src/parser/index';
-import getStringifier from '../../src/stringifier/index';
+import indent from '../../src/transforms/indent.js';
+import getParser from '../../src/parser/index.js';
+import getStringifier from '../../src/stringifier/index.js';
 
 test('push', () => {
   const source = `

package/tests/unit/transforms.spec.ts

@@ -1,6 +1,6 @@
-import { flow } from '../../src/transforms/index';
-import { seedBlock } from '../../src/util';
-import { Block } from '../../src/primitives';
+import { flow } from '../../src/transforms/index.js';
+import { seedBlock } from '../../src/util.js';
+import { Block } from '../../src/primitives.js';
 
 const t0 = (b: Block): Block => ({ ...b, description: b.description + ' t0' });
 const t1 = (b: Block): Block => ({ ...b, description: b.description + ' t1' });

package/tests/unit/util-rewire.spec.ts

@@ -1,4 +1,4 @@
-import { seedTokens, rewireSource, rewireSpecs } from '../../src/util';
+import { seedTokens, rewireSource, rewireSpecs } from '../../src/util.js';
 
 test('source to spec', () => {
   const block = {

package/tests/unit/util.spec.ts

@@ -6,7 +6,7 @@ import {
   splitLines,
   splitSpace,
   seedSpec,
-} from '../../src/util';
+} from '../../src/util.js';
 
 test.each([
   ['beginning', '\r to end', false],

package/tsconfig.json

@@ -1,8 +1,7 @@
 {
   "compilerOptions": {
     "target": "es2015",
-    "module": "es2015",
-    "moduleResolution": "node",
+    "module": "node16",
     "declaration": true,
     "outDir": "./es6",
     "lib": ["es2016", "es5"]

package/tsconfig.node.json

@@ -2,7 +2,7 @@
   "compilerOptions": {
     "target": "es2015",
     "module": "commonjs",
-    "moduleResolution": "node",
+    "moduleResolution": "node16",
     "declaration": true,
     "outDir": "./lib",
     "lib": ["es2016", "es5"]