@cjser/es-joy__jsdoccomment 0.96.0-cjser.2

package/src/parseComment.js

@@ -0,0 +1,190 @@
+/* eslint-disable prefer-named-capture-group -- Temporary */
+import {
+  parse as commentParser,
+  tokenizers
+} from 'comment-parser';
+
+import {parseInlineTags} from './parseInlineTags.js';
+
+const {
+  name: nameTokenizer,
+  tag: tagTokenizer,
+  type: typeTokenizer,
+  description: descriptionTokenizer
+} = tokenizers;
+
+/**
+ * @param {import('comment-parser').Spec} spec
+ * @returns {boolean}
+ */
+export const hasSeeWithLink = (spec) => {
+  return spec.tag === 'see' && (/\{@link.+?\}/v).test(spec.source[0].source);
+};
+
+export const defaultNoTypes = [
+  'default', 'defaultvalue', 'description', 'example',
+  'file', 'fileoverview', 'license',
+  'overview', 'see', 'summary'
+];
+
+export const defaultNoNames = [
+  'access', 'author',
+  'default', 'defaultvalue',
+  'description',
+  'example', 'exception', 'file', 'fileoverview',
+  'kind',
+  'license', 'overview',
+  'return', 'returns',
+  'since', 'summary',
+  'throws',
+  'version', 'variation'
+];
+
+const optionalBrackets = /^\[(?<name>[^=]*)=[^\]]*\]/v;
+const preserveTypeTokenizer = typeTokenizer('preserve');
+const preserveDescriptionTokenizer = descriptionTokenizer('preserve');
+const plainNameTokenizer = nameTokenizer();
+
+/**
+ * Can't import `comment-parser/es6/parser/tokenizers/index.js`,
+ *   so we redefine here.
+ * @typedef {(spec: import('comment-parser').Spec) =>
+ *   import('comment-parser').Spec} CommentParserTokenizer
+ */
+
+/**
+ * @param {object} [cfg]
+ * @param {string[]} [cfg.noTypes]
+ * @param {string[]} [cfg.noNames]
+ * @returns {CommentParserTokenizer[]}
+ */
+const getTokenizers = ({
+  noTypes = defaultNoTypes,
+  noNames = defaultNoNames
+} = {}) => {
+  // trim
+  return [
+    // Tag
+    tagTokenizer(),
+
+    /**
+     * Type tokenizer.
+     * @param {import('comment-parser').Spec} spec
+     * @returns {import('comment-parser').Spec}
+     */
+    (spec) => {
+      if (noTypes.includes(spec.tag)) {
+        return spec;
+      }
+
+      return preserveTypeTokenizer(spec);
+    },
+
+    /**
+     * Name tokenizer.
+     * @param {import('comment-parser').Spec} spec
+     * @returns {import('comment-parser').Spec}
+     */
+    (spec) => {
+      if (spec.tag === 'template') {
+        // const preWS = spec.postTag;
+        const remainder = spec.source[0].tokens.description;
+
+        let pos;
+        if (remainder.startsWith('[') && remainder.includes(']')) {
+          const endingBracketPos = remainder.lastIndexOf(']');
+          pos = remainder.slice(endingBracketPos).search(/(?<![\s,])\s/v);
+          if (pos > -1) { // Add offset to starting point if space found
+            pos += endingBracketPos;
+          }
+        } else {
+          pos = remainder.search(/(?<![\s,])\s/v);
+        }
+
+        const name = pos === -1 ? remainder : remainder.slice(0, pos);
+        const extra = remainder.slice(pos);
+        let postName = '', description = '', lineEnd = '';
+        if (pos > -1) {
+          [, postName, description, lineEnd] = /** @type {RegExpMatchArray} */ (
+            extra.match(/(\s*)([^\r]*)(\r)?/v)
+          );
+        }
+
+        spec.optional = optionalBrackets.test(name);
+        // name = /** @type {string} */ (
+        //   /** @type {RegExpMatchArray} */ (
+        //     name.match(optionalBrackets)
+        //   )?.groups?.name
+        // );
+
+        spec.name = name;
+        const {tokens} = spec.source[0];
+        tokens.name = name;
+        tokens.postName = postName;
+        tokens.description = description;
+        tokens.lineEnd = lineEnd || '';
+
+        return spec;
+      }
+
+      if (noNames.includes(spec.tag) || hasSeeWithLink(spec)) {
+        return spec;
+      }
+
+      return plainNameTokenizer(spec);
+    },
+
+    /**
+     * Description tokenizer.
+     * @param {import('comment-parser').Spec} spec
+     * @returns {import('comment-parser').Spec}
+     */
+    (spec) => {
+      return preserveDescriptionTokenizer(spec);
+    }
+  ];
+};
+
+/**
+ * Accepts a comment token or complete comment string and converts it into
+ * `comment-parser` AST.
+ * @param {string | {value: string}} commentOrNode
+ * @param {string} [indent] Whitespace
+ * @returns {import('./index.js').JsdocBlockWithInline}
+ */
+const parseComment = (commentOrNode, indent = '') => {
+  let result;
+
+  switch (typeof commentOrNode) {
+  case 'string':
+    // Preserve JSDoc block start/end indentation.
+    result = commentParser(`${indent}${commentOrNode}`, {
+      // @see https://github.com/yavorskiy/comment-parser/issues/21
+      tokenizers: getTokenizers()
+    });
+    break;
+  case 'object':
+    if (commentOrNode === null) {
+      throw new TypeError(`'commentOrNode' is not a string or object.`);
+    }
+
+    // Preserve JSDoc block start/end indentation.
+    result = commentParser(`${indent}/*${commentOrNode.value}*/`, {
+      // @see https://github.com/yavorskiy/comment-parser/issues/21
+      tokenizers: getTokenizers()
+    });
+    break;
+
+  default:
+    throw new TypeError(`'commentOrNode' is not a string or object.`);
+  }
+
+  if (!result.length) {
+    throw new Error('There were no results for comment parsing');
+  }
+
+  const [block] = result;
+  return parseInlineTags(block);
+};
+
+export {getTokenizers, parseComment};

package/src/parseInlineTags.js

@@ -0,0 +1,114 @@
+import {decodeInlineTagText} from './inlineTagEscapes.js';
+
+/**
+ * @param {RegExpMatchArray & {
+ *   indices: {
+ *     groups: {
+ *       [key: string]: [number, number]
+ *     }
+ *   }
+ *   groups: {[key: string]: string}
+ * }} match An inline tag regexp match.
+ * @returns {'pipe' | 'plain' | 'prefix' | 'space'}
+ */
+function determineFormat (match) {
+  const {separator, text} = match.groups;
+  const [, textEnd] = match.indices.groups.text;
+  const [tagStart] = match.indices.groups.tag;
+  if (!text) {
+    return 'plain';
+  }
+  if (separator === '|') {
+    return 'pipe';
+  }
+  if (textEnd < tagStart) {
+    return 'prefix';
+  }
+  return 'space';
+}
+
+/**
+ * Extracts inline tags from a description.
+ * @param {string} description
+ * @returns {import('./index.js').InlineTag[]} Array of inline tags from
+ *   the description.
+ */
+function parseDescription (description) {
+  /** @type {import('./index.js').InlineTag[]} */
+  const result = [];
+
+  // This could have been expressed in a single pattern,
+  // but having two avoids a potentially exponential time regex.
+
+  const prefixedTextPattern = /(?:\[(?<text>(?:[^\\\]]|\\[\s\S])+)\])\{@(?<tag>[^\}\s]+)\s?(?<namepathOrURL>[^\}\s\|]*)\}/gvd;
+  // The pattern used to match for text after tag uses a negative lookbehind
+  // on the ']' char to avoid matching the prefixed case too.
+  const suffixedAfterPattern = /(?<!\])\{@(?<tag>[^\}\s]+)\s?(?<namepathOrURL>[^\}\s\|]*)\s*(?<separator>[\s\|])?\s*(?<text>(?:[^\\\}]|\\[\s\S])*)\}/gvd;
+
+  const matches = [
+    ...description.matchAll(prefixedTextPattern),
+    ...description.matchAll(suffixedAfterPattern)
+  ];
+
+  for (const mtch of matches) {
+    const match = /**
+                   * @type {RegExpMatchArray & {
+                   *   indices: {
+                   *     groups: {
+                   *       [key: string]: [number, number]
+                   *     }
+                   *   }
+                   *   groups: {[key: string]: string}
+                   * }}
+                   */ (
+        mtch
+      );
+    const {tag, namepathOrURL, text} = match.groups;
+    const [start, end] = match.indices[0];
+    const format = determineFormat(match);
+    const decodedText = decodeInlineTagText(text, format);
+
+    result.push({
+      tag,
+      namepathOrURL,
+      text: decodedText,
+      format,
+      start,
+      end
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Splits the `{@ prefix}` from remaining `Spec.lines[].token.description`
+ * into the `inlineTags` tokens, and populates `spec.inlineTags`
+ * @param {import('comment-parser').Block} block
+ * @returns {import('./index.js').JsdocBlockWithInline}
+ */
+export function parseInlineTags (block) {
+  const inlineTags =
+    /**
+     * @type {(import('./commentParserToESTree.js').JsdocInlineTagNoType & {
+     *   line?: import('./commentParserToESTree.js').Integer
+     * })[]}
+     */ (
+      parseDescription(block.description)
+    );
+
+  /** @type {import('./index.js').JsdocBlockWithInline} */ (
+    block
+  ).inlineTags = inlineTags;
+
+  for (const tag of block.tags) {
+    /**
+     * @type {import('./index.js').JsdocTagWithInline}
+     */ (tag).inlineTags = parseDescription(tag.description);
+  }
+  return (
+    /**
+     * @type {import('./index.js').JsdocBlockWithInline}
+     */ (block)
+  );
+}

package/src/toCamelCase.js

@@ -0,0 +1,13 @@
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+const toCamelCase = (str) => {
+  return str.toLowerCase().replaceAll(/^[a-z]/gv, (init) => {
+    return init.toUpperCase();
+  }).replaceAll(/_(?<wordInit>[a-z])/gv, (_, n1, o, s, {wordInit}) => {
+    return wordInit.toUpperCase();
+  });
+};
+
+export {toCamelCase};