Fix actions/tour

node_modules/comment-parser/tests/e2e/examples.js

@@ -0,0 +1,244 @@
+// This file is a source for playground examples.
+// Examples integrity is smoke-checked with examples.spec.js
+
+function parse_defaults(source, parse, stringify, transforms) {
+  // Invoking parser with default config covers the most genearic cases.
+  // Note how /*** and /* blocks are ignored
+
+  /** One-liner */
+
+  /** @some-tag {someType} someName */
+
+  /**
+   * Description may go
+   * over multiple lines followed by @tags
+   * @param {string} name the name parameter
+   * @param {any} value the value parameter
+   */
+
+  /*** ignored */
+  /* ignored */
+
+  const parsed = parse(source);
+  const stringified = parsed.map((block) => stringify(block));
+}
+
+function parse_line_numbering(source, parse, stringify, transforms) {
+  // Note, line numbers are off by 5 from what you see in editor
+  //
+  // Try changeing start line back to 0, or omit the option
+  // parse(source, {startLine: 0}) -- default
+  // parse(source, {startLine: 5}) -- enforce alternative start number
+
+  /**
+   * Description may go
+   * over multiple lines followed by @tags
+   * @param {string} name the name parameter
+   * @param {any} value the value parameter
+   */
+
+  const parsed = parse(source, { startLine: 5 });
+  const stringified = parsed[0].tags
+    .map((tag) => `line ${tag.source[0].number + 1} : @${tag.tag} ${tag.name}`)
+    .join('\n');
+}
+
+function parse_spacing(source, parse, stringify, transforms) {
+  // Note, when spacing option is set to 'compact' or omited, tag and block descriptions are collapsed to look like a single sentense.
+  //
+  // Try changeing it to 'preserve' or defining custom function
+  // parse(source, {spacing: 'compact'}) -- default
+  // parse(source, {spacing: 'preserve'}) -- preserve spaces and line breaks
+  // parse(source, {spacing: lines => lines
+  //   .map(tokens => tokens.description.trim())
+  //   .filter(description => description !== '')
+  //   .join(' ');
+  // }) -- mimic 'compact' implementation
+
+  /**
+   * Description may go
+   * over multiple lines followed by
+   * @param {string} name the name parameter
+   *   with multiline description
+   * @param {function(
+   *   number,
+   *   string
+   * )} options the options
+   */
+
+  const parsed = parse(source, { spacing: 'preserve' });
+  const stringified = parsed[0].tags
+    .map((tag) => `@${tag.tag} - ${tag.description}\n\n${tag.type}`)
+    .join('\n----\n');
+}
+
+function parse_escaping(source, parse, stringify, transforms) {
+  // Note, @decorator is not parsed as another tag because block is wrapped into ###.
+  //
+  // Try setting alternative escape sequence
+  // parse(source, {fence: '```'}) -- default
+  // parse(source, {fence: '###'}) -- update source correspondingly
+
+  /**
+   * @example "some code"
+  ###
+  @decorator
+  function hello() {
+    // do something
+  }
+  ###
+   */
+
+  const parsed = parse(source, { fence: '###' });
+  const stringified = parsed[0].tags
+    .map((tag) => `@${tag.tag} - ${tag.description}`)
+    .join('\n');
+}
+
+function stringify_formatting(source, parse, stringify, transforms) {
+  // stringify preserves exact formatting by default, but you can transform parsing result first
+  // transform = align() -- align name, type, and description
+  // transform = flow(align(), indent(4)) -- align, then place the block's opening marker at pos 4
+
+  /**
+   * Description may go
+   * over multiple lines followed by @tags
+   * @param {string} name the name parameter
+   * @param {any} value the value parameter
+   */
+
+  const { flow, align, indent } = transforms;
+  const transform = flow(align(), indent(4));
+
+  const parsed = parse(source);
+  const stringified = stringify(transform(parsed[0]));
+}
+
+function parse_source_exploration(source, parse, stringify, transforms) {
+  // parse() produces Block[].source keeping accurate track of origin source
+
+  /**
+   * Description may go
+   * over multiple lines followed by @tags
+   * @param {string} name the name parameter
+   * @param {any} value the value parameter
+   */
+
+  const parsed = parse(source);
+
+  const summary = ({ source }) => ({
+    source: source
+      .map(
+        ({ tokens }) =>
+          tokens.start +
+          tokens.delimiter +
+          tokens.postDelimiter +
+          tokens.tag +
+          tokens.postTag +
+          tokens.type +
+          tokens.postType +
+          tokens.name +
+          tokens.postName +
+          tokens.description +
+          tokens.end
+      )
+      .join('\n'),
+    start: {
+      line: source[0].number + 1,
+      column: source[0].tokens.start.length,
+    },
+    end: {
+      line: source[source.length - 1].number + 1,
+      column: source[source.length - 1].source.length,
+    },
+  });
+
+  const pos = (p) => p.line + ':' + p.column;
+
+  const stringified = parsed[0].tags
+    .map(summary)
+    .map((s) => `${pos(s.start)} - ${pos(s.end)}\n${s.source}`);
+}
+
+function parse_advanced_parsing(source, parse, _, _, tokenizers) {
+  // Each '@tag ...' section results into a Spec. The Spec is computed by
+  // the chain of tokenizers each contributing a change to the the Spec.* and the Spec.tags[].tokens.
+  // Default parse() options come with stadart tokenizers:
+  // {
+  //   ...,
+  //   spacing = 'compact',
+  //   tokenizers = [
+  //     tokenizers.tag(),
+  //     tokenizers.type(spacing),
+  //     tokenizers.name(),
+  //     tokenizers.description(spacing),
+  //   ]
+  // }
+  // You can reorder those, or even replace any with a custom function (spec: Spec) => Spec
+  // This example allows to parse "@tag description" comments
+
+  /**
+   * @arg0 my parameter
+   * @arg1
+   *   another parameter
+   *      with a strange formatting
+   */
+
+  const parsed = parse(source, {
+    tokenizers: [tokenizers.tag(), tokenizers.description('preserve')],
+  });
+  const stringified = parsed[0].tags
+    .map((tag) => `@${tag.tag} - ${tag.description}`)
+    .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,
+  parse_escaping,
+  parse_spacing,
+  parse_source_exploration,
+  parse_advanced_parsing,
+  stringify_formatting,
+  stringify_rename,
+];

node_modules/comment-parser/tests/e2e/examples.spec.js

@@ -0,0 +1,16 @@
+const {
+  parse,
+  stringify,
+  transforms,
+  tokenizers,
+} = require('../../lib/index.cjs');
+const { examples } = require('./examples');
+
+const table = examples.map((fn) => [fn.name.replace(/_/g, ' '), fn]);
+
+test.each(table)('example - %s', (name, fn) => {
+  const source = fn.toString();
+  expect(() =>
+    fn(source, parse, stringify, transforms, tokenizers)
+  ).not.toThrow();
+});

node_modules/comment-parser/tests/e2e/issue-109.spec.js

@@ -0,0 +1,49 @@
+const { parse, inspect } = require('../../lib/index.cjs');
+
+const source = `
+  /**
+   * Typedef with multi-line property type.
+   *
+   * @typedef {object} MyType
+   * @property {function(
+   *   number,
+   *   {x:string}
+   * )} numberEater Method
+   *    which takes a number.
+   */`;
+
+test('default', () => {
+  const parsed = parse(source);
+  // console.log(inspect(parsed[0]));
+  expect(parsed[0].tags[1]).toMatchObject({
+    tag: 'property',
+    type: 'function(number,{x:string})',
+    name: 'numberEater',
+    description: 'Method which takes a number.',
+    problems: [],
+  });
+});
+
+test('preserve', () => {
+  const parsed = parse(source, { spacing: 'preserve' });
+  // console.log(inspect(parsed[0]));
+  expect(parsed[0].tags[1]).toMatchObject({
+    tag: 'property',
+    type: 'function(\n  number,\n  {x:string}\n)',
+    name: 'numberEater',
+    description: 'Method\n   which takes a number.',
+    problems: [],
+  });
+});
+
+test('compact', () => {
+  const parsed = parse(source, { spacing: 'compact' });
+  // console.log(inspect(parsed[0]));
+  expect(parsed[0].tags[1]).toMatchObject({
+    tag: 'property',
+    type: 'function(number,{x:string})',
+    name: 'numberEater',
+    description: 'Method which takes a number.',
+    problems: [],
+  });
+});

node_modules/comment-parser/tests/e2e/issue-112.spec.js

@@ -0,0 +1,20 @@
+const { parse, inspect } = require('../../lib/index.cjs');
+
+const source = `
+  /**
+   * @param {Function} [processor=data => data] A function to run
+   */`;
+
+test('default', () => {
+  const parsed = parse(source);
+  // console.log(inspect(parsed[0]));
+
+  expect(parsed[0].problems).toEqual([]);
+  expect(parsed[0].tags[0]).toMatchObject({
+    name: 'processor',
+    default: 'data => data',
+    optional: true,
+    description: 'A function to run',
+    problems: [],
+  });
+});

node_modules/comment-parser/tests/e2e/issue-113.spec.js

@@ -0,0 +1,23 @@
+const { parse, inspect } = require('../../lib/index.cjs');
+
+const source = `
+  /** Multi-line typedef for an options object type.
+   *
+   * @typedef {{
+   *   prop: number
+   * }} MyOptions description text
+   */`;
+
+test('name after multiline tag', () => {
+  const parsed = parse(source);
+  // console.log(inspect(parsed[0]));
+
+  expect(parsed[0].problems).toEqual([]);
+  expect(parsed[0].tags[0]).toMatchObject({
+    tag: 'typedef',
+    name: 'MyOptions',
+    type: '{prop: number}',
+    description: 'description text',
+    problems: [],
+  });
+});

node_modules/comment-parser/tests/e2e/issue-119.spec.js

@@ -0,0 +1,29 @@
+const {
+  parse,
+  stringify,
+  transforms: { align },
+} = require('../../lib/index.cjs');
+
+test('align - ignore trailing right space', () => {
+  const source = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     * @param {string} name
+     * @param {any} value the value parameter
+     */`;
+
+  const expected = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     * @param {string} name
+     * @param {any}    value the value parameter
+     */`.slice(1);
+
+  const parsed = parse(source);
+  const aligned = align()(parsed[0]);
+  const stringified = stringify(aligned);
+
+  expect(stringified).toEqual(expected);
+});

node_modules/comment-parser/tests/e2e/issue-120.spec.js

@@ -0,0 +1,29 @@
+const {
+  parse,
+  stringify,
+  transforms: { align },
+} = require('../../lib/index.cjs');
+
+test('align - collapse postDelim', () => {
+  const source = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     *        @param {string} name the name parameter
+     * @param {any} value the value parameter
+     */`.slice(1);
+
+  const expected = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     * @param {string} name  the name parameter
+     * @param {any}    value the value parameter
+     */`.slice(1);
+
+  const parsed = parse(source);
+  const aligned = align()(parsed[0]);
+  const stringified = stringify(aligned);
+
+  expect(stringified).toEqual(expected);
+});

node_modules/comment-parser/tests/e2e/issue-121.spec.js

@@ -0,0 +1,105 @@
+const { parse, inspect } = require('../../lib/index.cjs');
+
+test('name cut off', () => {
+  const source = `
+    /**
+     * @param {{includeWhiteSpace: (boolean|undefined),
+     *    ignoreElementOrder: (boolean|undefined)}} [options] The options.
+     */`.slice(1);
+
+  const tagSource = [
+    {
+      number: 1,
+      source: '     * @param {{includeWhiteSpace: (boolean|undefined),',
+      tokens: {
+        start: '     ',
+        delimiter: '*',
+        postDelimiter: ' ',
+        tag: '@param',
+        postTag: ' ',
+        type: '{{includeWhiteSpace: (boolean|undefined),',
+        postType: '',
+        name: '',
+        postName: '',
+        description: '',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 2,
+      source:
+        '     *    ignoreElementOrder: (boolean|undefined)}} [options] The options.',
+      tokens: {
+        start: '     ',
+        delimiter: '*',
+        postDelimiter: ' ',
+        tag: '',
+        postTag: '',
+        type: '   ignoreElementOrder: (boolean|undefined)}}',
+        postType: ' ',
+        name: '[options]',
+        postName: ' ',
+        description: 'The options.',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 3,
+      source: '     */',
+      tokens: {
+        start: '     ',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        type: '',
+        postType: '',
+        name: '',
+        postName: '',
+        description: '',
+        end: '*/',
+        lineEnd: '',
+      },
+    },
+  ];
+
+  const parsed = parse(source);
+  // console.log(inspect(parsed[0]));
+
+  expect(parsed[0]).toMatchObject({
+    problems: [],
+    tags: [
+      {
+        tag: 'param',
+        type: '{includeWhiteSpace: (boolean|undefined),ignoreElementOrder: (boolean|undefined)}',
+        name: 'options',
+        optional: true,
+        description: 'The options.',
+        source: tagSource,
+      },
+    ],
+    source: [
+      {
+        number: 0,
+        source: '    /**',
+        tokens: {
+          start: '    ',
+          delimiter: '/**',
+          postDelimiter: '',
+          tag: '',
+          postTag: '',
+          type: '',
+          postType: '',
+          name: '',
+          postName: '',
+          description: '',
+          end: '',
+          lineEnd: '',
+        },
+      },
+      ...tagSource,
+    ],
+  });
+});

node_modules/comment-parser/tests/e2e/issue-129.spec.js

@@ -0,0 +1,143 @@
+const {
+  parse,
+  inspect,
+  stringify,
+  transforms: { align },
+} = require('../../lib/index.cjs');
+
+const tokens = {
+  start: '',
+  delimiter: '',
+  postDelimiter: '',
+  tag: '',
+  postTag: '',
+  type: '',
+  postType: '',
+  name: '',
+  postName: '',
+  description: '',
+  end: '',
+  lineEnd: '',
+};
+
+test('carriage returns', () => {
+  const parsed = parse(`
+    /**
+     * description\r
+     * @param0 {param-type}\r
+     * @param1 {param-type} paramName param description\r
+     */`);
+
+  const source = [
+    {
+      number: 1,
+      source: '    /**',
+      tokens: {
+        ...tokens,
+        start: '    ',
+        delimiter: '/**',
+      },
+    },
+    {
+      number: 2,
+      source: '     * description\r',
+      tokens: {
+        ...tokens,
+        start: '     ',
+        delimiter: '*',
+        postDelimiter: ' ',
+        description: 'description',
+        lineEnd: '\r',
+      },
+    },
+    {
+      number: 3,
+      source: '     * @param0 {param-type}\r',
+      tokens: {
+        ...tokens,
+        start: '     ',
+        delimiter: '*',
+        postDelimiter: ' ',
+        tag: '@param0',
+        postTag: ' ',
+        type: '{param-type}',
+        lineEnd: '\r',
+      },
+    },
+    {
+      number: 4,
+      source: '     * @param1 {param-type} paramName param description\r',
+      tokens: {
+        ...tokens,
+        start: '     ',
+        delimiter: '*',
+        postDelimiter: ' ',
+        tag: '@param1',
+        postTag: ' ',
+        type: '{param-type}',
+        postType: ' ',
+        name: 'paramName',
+        postName: ' ',
+        description: 'param description',
+        lineEnd: '\r',
+      },
+    },
+    {
+      number: 5,
+      source: '     */',
+      tokens: {
+        ...tokens,
+        start: '     ',
+        end: '*/',
+      },
+    },
+  ];
+
+  expect(parsed[0]).toMatchObject({
+    description: 'description',
+    problems: [],
+    source,
+    tags: [
+      {
+        tag: 'param0',
+        type: 'param-type',
+        name: '',
+        optional: false,
+        description: '',
+        source: [source[2]],
+      },
+      {
+        tag: 'param1',
+        type: 'param-type',
+        name: 'paramName',
+        optional: false,
+        description: 'param description',
+        source: [source[3], source[4]],
+      },
+    ],
+  });
+});
+
+test('carriage returns with alignment', () => {
+  const source = `
+     /**\r
+      * Description may go\r
+      * over multiple lines followed by @tags\r
+      *  @param {string} name the name parameter\r
+      *     @param {any} value\r
+      */\r`.slice(1);
+
+  const expected = `
+     /**\r
+      * Description may go\r
+      * over multiple lines followed by @tags\r
+      * @param {string} name  the name parameter\r
+      * @param {any}    value\r
+      */\r`.slice(1);
+
+  const parsed = parse(source);
+  const aligned = align()(parsed[0]);
+  const stringified = stringify(aligned);
+
+  expect(stringified).toEqual(expected);
+});

node_modules/comment-parser/tests/e2e/issue-41.spec.js

@@ -0,0 +1,362 @@
+const { default: getParser } = require('../../lib/parser/index.cjs');
+
+test('quoted name', () => {
+  const parsed = getParser()(`
+  /**
+   * @section "Brand Colors" - Here you can find all the brand colors...
+   */`);
+
+  expect(parsed).toEqual([
+    {
+      description: '',
+      tags: [
+        {
+          tag: 'section',
+          name: 'Brand Colors',
+          type: '',
+          optional: false,
+          description: '- Here you can find all the brand colors...',
+          problems: [],
+          source: [
+            {
+              number: 2,
+              source:
+                '   * @section "Brand Colors" - Here you can find all the brand colors...',
+              tokens: {
+                start: '   ',
+                delimiter: '*',
+                postDelimiter: ' ',
+                tag: '@section',
+                postTag: ' ',
+                name: '"Brand Colors"',
+                postName: ' ',
+                type: '',
+                postType: '',
+                description: '- Here you can find all the brand colors...',
+                end: '',
+                lineEnd: '',
+              },
+            },
+            {
+              number: 3,
+              source: '   */',
+              tokens: {
+                start: '   ',
+                delimiter: '',
+                postDelimiter: '',
+                tag: '',
+                postTag: '',
+                name: '',
+                postName: '',
+                type: '',
+                postType: '',
+                description: '',
+                end: '*/',
+                lineEnd: '',
+              },
+            },
+          ],
+        },
+      ],
+      source: [
+        {
+          number: 1,
+          source: '  /**',
+          tokens: {
+            start: '  ',
+            delimiter: '/**',
+            postDelimiter: '',
+            tag: '',
+            postTag: '',
+            name: '',
+            postName: '',
+            type: '',
+            postType: '',
+            description: '',
+            end: '',
+            lineEnd: '',
+          },
+        },
+        {
+          number: 2,
+          source:
+            '   * @section "Brand Colors" - Here you can find all the brand colors...',
+          tokens: {
+            start: '   ',
+            delimiter: '*',
+            postDelimiter: ' ',
+            tag: '@section',
+            postTag: ' ',
+            name: '"Brand Colors"',
+            postName: ' ',
+            type: '',
+            postType: '',
+            description: '- Here you can find all the brand colors...',
+            end: '',
+            lineEnd: '',
+          },
+        },
+        {
+          number: 3,
+          source: '   */',
+          tokens: {
+            start: '   ',
+            delimiter: '',
+            postDelimiter: '',
+            tag: '',
+            postTag: '',
+            name: '',
+            postName: '',
+            type: '',
+            postType: '',
+            description: '',
+            end: '*/',
+            lineEnd: '',
+          },
+        },
+      ],
+      problems: [],
+    },
+  ]);
+});
+
+test('optional name', () => {
+  const parsed = getParser()(`
+  /**
+   * @section [Brand Colors] - Here you can find all the brand colors...
+   */`);
+
+  expect(parsed).toEqual([
+    {
+      description: '',
+      tags: [
+        {
+          tag: 'section',
+          name: 'Brand Colors',
+          type: '',
+          optional: true,
+          description: '- Here you can find all the brand colors...',
+          problems: [],
+          source: [
+            {
+              number: 2,
+              source:
+                '   * @section [Brand Colors] - Here you can find all the brand colors...',
+              tokens: {
+                start: '   ',
+                delimiter: '*',
+                postDelimiter: ' ',
+                tag: '@section',
+                postTag: ' ',
+                name: '[Brand Colors]',
+                postName: ' ',
+                type: '',
+                postType: '',
+                description: '- Here you can find all the brand colors...',
+                end: '',
+                lineEnd: '',
+              },
+            },
+            {
+              number: 3,
+              source: '   */',
+              tokens: {
+                start: '   ',
+                delimiter: '',
+                postDelimiter: '',
+                tag: '',
+                postTag: '',
+                name: '',
+                postName: '',
+                type: '',
+                postType: '',
+                description: '',
+                end: '*/',
+                lineEnd: '',
+              },
+            },
+          ],
+        },
+      ],
+      source: [
+        {
+          number: 1,
+          source: '  /**',
+          tokens: {
+            start: '  ',
+            delimiter: '/**',
+            postDelimiter: '',
+            tag: '',
+            postTag: '',
+            name: '',
+            postName: '',
+            type: '',
+            postType: '',
+            description: '',
+            end: '',
+            lineEnd: '',
+          },
+        },
+        {
+          number: 2,
+          source:
+            '   * @section [Brand Colors] - Here you can find all the brand colors...',
+          tokens: {
+            start: '   ',
+            delimiter: '*',
+            postDelimiter: ' ',
+            tag: '@section',
+            postTag: ' ',
+            name: '[Brand Colors]',
+            postName: ' ',
+            type: '',
+            postType: '',
+            description: '- Here you can find all the brand colors...',
+            end: '',
+            lineEnd: '',
+          },
+        },
+        {
+          number: 3,
+          source: '   */',
+          tokens: {
+            start: '   ',
+            delimiter: '',
+            postDelimiter: '',
+            tag: '',
+            postTag: '',
+            name: '',
+            postName: '',
+            type: '',
+            postType: '',
+            description: '',
+            end: '*/',
+            lineEnd: '',
+          },
+        },
+      ],
+      problems: [],
+    },
+  ]);
+});
+
+test('inconsistent quotes', () => {
+  const parsed = getParser()(`
+  /**
+   * @section "Brand Colors - Here you can find all the brand colors...
+   */`);
+
+  expect(parsed).toEqual([
+    {
+      description: '',
+      tags: [
+        {
+          tag: 'section',
+          name: '"Brand',
+          type: '',
+          optional: false,
+          description: 'Colors - Here you can find all the brand colors...',
+          problems: [],
+          source: [
+            {
+              number: 2,
+              source:
+                '   * @section "Brand Colors - Here you can find all the brand colors...',
+              tokens: {
+                start: '   ',
+                delimiter: '*',
+                postDelimiter: ' ',
+                tag: '@section',
+                postTag: ' ',
+                name: '"Brand',
+                postName: ' ',
+                type: '',
+                postType: '',
+                description:
+                  'Colors - Here you can find all the brand colors...',
+                end: '',
+                lineEnd: '',
+              },
+            },
+            {
+              number: 3,
+              source: '   */',
+              tokens: {
+                start: '   ',
+                delimiter: '',
+                postDelimiter: '',
+                tag: '',
+                postTag: '',
+                name: '',
+                postName: '',
+                type: '',
+                postType: '',
+                description: '',
+                end: '*/',
+                lineEnd: '',
+              },
+            },
+          ],
+        },
+      ],
+      source: [
+        {
+          number: 1,
+          source: '  /**',
+          tokens: {
+            start: '  ',
+            delimiter: '/**',
+            postDelimiter: '',
+            tag: '',
+            postTag: '',
+            name: '',
+            postName: '',
+            type: '',
+            postType: '',
+            description: '',
+            end: '',
+            lineEnd: '',
+          },
+        },
+        {
+          number: 2,
+          source:
+            '   * @section "Brand Colors - Here you can find all the brand colors...',
+          tokens: {
+            start: '   ',
+            delimiter: '*',
+            postDelimiter: ' ',
+            tag: '@section',
+            postTag: ' ',
+            name: '"Brand',
+            postName: ' ',
+            type: '',
+            postType: '',
+            description: 'Colors - Here you can find all the brand colors...',
+            end: '',
+            lineEnd: '',
+          },
+        },
+        {
+          number: 3,
+          source: '   */',
+          tokens: {
+            start: '   ',
+            delimiter: '',
+            postDelimiter: '',
+            tag: '',
+            postTag: '',
+            name: '',
+            postName: '',
+            type: '',
+            postType: '',
+            description: '',
+            end: '*/',
+            lineEnd: '',
+          },
+        },
+      ],
+      problems: [],
+    },
+  ]);
+});

node_modules/comment-parser/tests/e2e/issue-61.spec.js

@@ -0,0 +1,581 @@
+const { default: getParser } = require('../../lib/parser/index.cjs');
+
+test('fenced description', () => {
+  const parsed = getParser({ spacing: 'preserve' })(`
+  /**
+   * @example "" \`\`\`ts
+@transient()
+class Foo { }
+\`\`\`
+  */`);
+
+  const source = [
+    {
+      number: 1,
+      source: '  /**',
+      tokens: {
+        start: '  ',
+        delimiter: '/**',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 2,
+      source: '   * @example "" ```ts',
+      tokens: {
+        start: '   ',
+        delimiter: '*',
+        postDelimiter: ' ',
+        tag: '@example',
+        postTag: ' ',
+        name: '""',
+        postName: ' ',
+        type: '',
+        postType: '',
+        description: '```ts',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 3,
+      source: '@transient()',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '@transient()',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 4,
+      source: 'class Foo { }',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: 'class Foo { }',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 5,
+      source: '```',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '```',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 6,
+      source: '  */',
+      tokens: {
+        start: '  ',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '',
+        end: '*/',
+        lineEnd: '',
+      },
+    },
+  ];
+
+  expect(parsed).toEqual([
+    {
+      description: '',
+      tags: [
+        {
+          tag: 'example',
+          name: '',
+          type: '',
+          optional: false,
+          description: '```ts\n@transient()\nclass Foo { }\n```',
+          problems: [],
+          source: source.slice(1),
+        },
+      ],
+      source,
+      problems: [],
+    },
+  ]);
+});
+
+test('fenced one-liner', () => {
+  const parsed = getParser({ spacing: 'preserve' })(
+    '/** @example "" ```ts @transient() class Foo { } ```*/'
+  );
+
+  const source = [
+    {
+      number: 0,
+      source: '/** @example "" ```ts @transient() class Foo { } ```*/',
+      tokens: {
+        start: '',
+        delimiter: '/**',
+        postDelimiter: ' ',
+        tag: '@example',
+        postTag: ' ',
+        name: '""',
+        postName: ' ',
+        type: '',
+        postType: '',
+        description: '```ts @transient() class Foo { } ```',
+        end: '*/',
+        lineEnd: '',
+      },
+    },
+  ];
+
+  expect(parsed).toEqual([
+    {
+      description: '',
+      tags: [
+        {
+          tag: 'example',
+          name: '',
+          type: '',
+          optional: false,
+          description: '```ts @transient() class Foo { } ```',
+          problems: [],
+          source,
+        },
+      ],
+      source,
+      problems: [],
+    },
+  ]);
+});
+
+test('multiple fences', () => {
+  const parsed = getParser({ spacing: 'preserve' })(`
+  /**
+   * @example "" \`\`\`ts
+@one
+\`\`\`
+text
+\`\`\`
+@two
+\`\`\`
+  */`);
+
+  const source = [
+    {
+      number: 1,
+      source: '  /**',
+      tokens: {
+        start: '  ',
+        delimiter: '/**',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 2,
+      source: '   * @example "" ```ts',
+      tokens: {
+        start: '   ',
+        delimiter: '*',
+        postDelimiter: ' ',
+        tag: '@example',
+        postTag: ' ',
+        name: '""',
+        postName: ' ',
+        type: '',
+        postType: '',
+        description: '```ts',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 3,
+      source: '@one',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '@one',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 4,
+      source: '```',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '```',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 5,
+      source: 'text',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: 'text',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 6,
+      source: '```',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '```',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 7,
+      source: '@two',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '@two',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 8,
+      source: '```',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '```',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 9,
+      source: '  */',
+      tokens: {
+        start: '  ',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '',
+        end: '*/',
+        lineEnd: '',
+      },
+    },
+  ];
+
+  expect(parsed).toEqual([
+    {
+      description: '',
+      tags: [
+        {
+          tag: 'example',
+          name: '',
+          type: '',
+          optional: false,
+          description: '```ts\n@one\n```\ntext\n```\n@two\n```',
+          source: source.slice(1),
+          problems: [],
+        },
+      ],
+      source,
+      problems: [],
+    },
+  ]);
+});
+
+test('custom fences', () => {
+  const parsed = getParser({ spacing: 'preserve', fence: '###' })(`
+  /**
+   * @example "" ###ts
+@one
+###
+text
+###
+@two
+###
+  */`);
+
+  const source = [
+    {
+      number: 1,
+      source: '  /**',
+      tokens: {
+        start: '  ',
+        delimiter: '/**',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 2,
+      source: '   * @example "" ###ts',
+      tokens: {
+        start: '   ',
+        delimiter: '*',
+        postDelimiter: ' ',
+        tag: '@example',
+        postTag: ' ',
+        name: '""',
+        postName: ' ',
+        type: '',
+        postType: '',
+        description: '###ts',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 3,
+      source: '@one',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '@one',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 4,
+      source: '###',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '###',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 5,
+      source: 'text',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: 'text',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 6,
+      source: '###',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '###',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 7,
+      source: '@two',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '@two',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 8,
+      source: '###',
+      tokens: {
+        start: '',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '###',
+        end: '',
+        lineEnd: '',
+      },
+    },
+    {
+      number: 9,
+      source: '  */',
+      tokens: {
+        start: '  ',
+        delimiter: '',
+        postDelimiter: '',
+        tag: '',
+        postTag: '',
+        name: '',
+        postName: '',
+        type: '',
+        postType: '',
+        description: '',
+        end: '*/',
+        lineEnd: '',
+      },
+    },
+  ];
+
+  expect(parsed).toEqual([
+    {
+      description: '',
+      tags: [
+        {
+          tag: 'example',
+          name: '',
+          type: '',
+          optional: false,
+          description: '###ts\n@one\n###\ntext\n###\n@two\n###',
+          source: source.slice(1),
+          problems: [],
+        },
+      ],
+      source,
+      problems: [],
+    },
+  ]);
+});

node_modules/comment-parser/tests/e2e/stringify.spec.js

@@ -0,0 +1,13 @@
+const { parse, stringify } = require('../../lib/index.cjs');
+
+test('preserve formatting', () => {
+  const source = `
+  /**
+* @my-tag {my.type} my-name description line 1
+      description line 2
+    * description line 3
+   */`;
+  const parsed = parse(source);
+  const out = stringify(parsed[0]);
+  expect(out).toBe(source.slice(1));
+});

node_modules/comment-parser/tests/e2e/transforms.spec.js

@@ -0,0 +1,32 @@
+const {
+  parse,
+  stringify,
+  transforms: { flow, indent, align },
+} = require('../../lib/index.cjs');
+
+test('align + indent', () => {
+  const source = `
+  /**
+   * Description may go
+   * over multiple lines followed by @tags
+   *
+* @my-tag {my.type} my-name description line 1
+      description line 2
+      * description line 3
+   */`;
+
+  const expected = `
+    /**
+     * Description may go
+     * over multiple lines followed by @tags
+     *
+     * @my-tag {my.type} my-name description line 1
+                                 description line 2
+     *                           description line 3
+     */`;
+
+  const parsed = parse(source);
+  const transform = flow(indent(4), align());
+  const out = stringify(transform(parsed[0]));
+  expect(out).toBe(expected.slice(1));
+});