@cjser/es-joy__jsdoccomment 0.96.0-cjser.2

package/src/estreeToString.js

@@ -0,0 +1,234 @@
+import {stringify as prattStringify} from '@cjser/jsdoc-type-pratt-parser';
+
+import {encodeInlineTagText} from './inlineTagEscapes.js';
+
+/* eslint-disable jsdoc/reject-function-type -- Different functions */
+/** @type {Record<string, Function>} */
+const stringifiers = {
+  /* eslint-enable jsdoc/reject-function-type -- Different functions */
+  JsdocBlock,
+
+  /**
+   * @param {import('./commentParserToESTree.js').JsdocDescriptionLine} node
+   * @returns {string}
+   */
+  JsdocDescriptionLine ({
+    initial, delimiter, postDelimiter, description
+  }) {
+    return `${initial}${delimiter}${postDelimiter}${description}`;
+  },
+
+  /**
+   * @param {import('./commentParserToESTree.js').JsdocTypeLine} node
+   * @returns {string}
+   */
+  JsdocTypeLine ({
+    initial, delimiter, postDelimiter, rawType
+  }) {
+    return `${initial}${delimiter}${postDelimiter}${rawType}`;
+  },
+
+  /**
+   * @param {import('./commentParserToESTree.js').JsdocInlineTag} node
+   */
+  JsdocInlineTag ({format, namepathOrURL, tag, text}) {
+    const encodedText = encodeInlineTagText(text, format);
+    return format === 'pipe'
+      ? `{@${tag} ${namepathOrURL}|${encodedText}}`
+      : format === 'plain'
+        ? `{@${tag} ${namepathOrURL}}`
+        : format === 'prefix'
+          ? `[${encodedText}]{@${tag} ${namepathOrURL}}`
+          // "space"
+          : `{@${tag} ${namepathOrURL} ${encodedText}}`;
+  },
+
+  JsdocTag
+};
+
+/**
+ * @todo convert for use by escodegen (until may be patched to support
+ *   custom entries?).
+ * @param {import('./commentParserToESTree.js').JsdocBlock|
+ *   import('./commentParserToESTree.js').JsdocDescriptionLine|
+ *   import('./commentParserToESTree.js').JsdocTypeLine|
+ *   import('./commentParserToESTree.js').JsdocTag|
+ *   import('./commentParserToESTree.js').JsdocInlineTag|
+ *   import('@cjser/jsdoc-type-pratt-parser').RootResult
+ * } node
+ * @param {import('./index.js').ESTreeToStringOptions} [opts]
+ * @throws {Error}
+ * @returns {string}
+ */
+function estreeToString (node, opts = {}) {
+  if (Object.hasOwn(stringifiers, node.type)) {
+    return stringifiers[
+      /**
+       * @type {import('./commentParserToESTree.js').JsdocBlock|
+       *   import('./commentParserToESTree.js').JsdocDescriptionLine|
+       *   import('./commentParserToESTree.js').JsdocTypeLine|
+       *   import('./commentParserToESTree.js').JsdocTag}
+       */
+      (node).type
+    ](
+      node,
+      opts
+    );
+  }
+
+  // We use raw type instead but it is a key as other apps may wish to traverse
+  if (node.type.startsWith('JsdocType')) {
+    return opts.preferRawType
+      ? ''
+      : `{${prattStringify(
+        /** @type {import('@cjser/jsdoc-type-pratt-parser').RootResult} */ (
+          node
+        ),
+        opts.jtppStringificationRules
+      )}}`;
+  }
+
+  throw new Error(`Unhandled node type: ${node.type}`);
+}
+
+/**
+ * @param {import('./commentParserToESTree.js').JsdocBlock} node
+ * @param {import('./index.js').ESTreeToStringOptions} opts
+ * @returns {string}
+ */
+function JsdocBlock (node, opts) {
+  const {delimiter, delimiterLineBreak, descriptionLines,
+    initial, postDelimiter, preterminalLineBreak, tags, terminal} = node;
+
+  const terminalPrepend = preterminalLineBreak !== ''
+    ? `${preterminalLineBreak}${initial} `
+    : '';
+
+  let result = `${initial}${delimiter}${postDelimiter}${delimiterLineBreak}`;
+
+  for (let i = 0; i < descriptionLines.length; i++) {
+    result += estreeToString(descriptionLines[i]);
+
+    if (i !== descriptionLines.length - 1 || tags.length) {
+      result += '\n';
+    }
+  }
+
+  for (let i = 0; i < tags.length; i++) {
+    result += estreeToString(tags[i], opts);
+
+    if (i !== tags.length - 1) {
+      result += '\n';
+    }
+  }
+
+  result += `${terminalPrepend}${terminal}`;
+
+  return result;
+}
+
+/**
+ * @param {import('./commentParserToESTree.js').JsdocTag} node
+ * @param {import('./index.js').ESTreeToStringOptions} opts
+ * @returns {string}
+ */
+function JsdocTag (node, opts) {
+  const {
+    delimiter, descriptionLines, initial, name, parsedType, postDelimiter,
+    postName, postTag, postType, tag, typeLines
+  } = node;
+
+  let result = `${initial}${delimiter}${postDelimiter}@${tag}${postTag}`;
+
+  // Could do `rawType` but may have been changed; could also do
+  //   `typeLines` but not as likely to be changed
+  // parsedType
+  // Comment this out later in favor of `parsedType`
+  // We can't use raw `typeLines` as first argument has delimiter on it
+  if (!parsedType || opts.preferRawType) {
+    if (typeLines.length) {
+      result += '{';
+
+      for (let i = 0; i < typeLines.length; i++) {
+        result += estreeToString(typeLines[i]);
+
+        if (i !== typeLines.length - 1) {
+          result += '\n';
+        }
+      }
+
+      result += '}';
+    }
+    /* v8 ignore start */
+  } else if (parsedType?.type.startsWith('JsdocType')) {
+    result += `{${prattStringify(
+      /** @type {import('@cjser/jsdoc-type-pratt-parser').RootResult} */ (
+        parsedType
+      )
+    )}}`;
+    /* v8 ignore stop */
+  }
+
+  // Check if the name appears on a separate line from the tag/type
+  // This is indicated by postTag and postType both being empty
+  let nameLineOffset = 0;
+  if (name && postTag === '' && postType === '') {
+    // The name is on a separate line from the tag
+    result += '\n';
+
+    if (descriptionLines.length > 0) {
+      const firstDescLine = descriptionLines[0];
+      /* v8 ignore next 3 */
+      if (firstDescLine.description === '' && firstDescLine.delimiter === '' &&
+          firstDescLine.postDelimiter === '' && firstDescLine.initial === '') {
+        // Empty first line, check if there's a second line with formatting
+        if (descriptionLines.length > 1) {
+          const nameLine = descriptionLines[1];
+          result += `${
+            nameLine.initial
+          }${nameLine.delimiter}${
+            nameLine.postDelimiter
+          }${name}${postName}${
+            nameLine.description
+          }`;
+          nameLineOffset = 2;
+        } else {
+          /* v8 ignore start */
+          // Fallback: just add name (shouldn't normally happen)
+          result += name + postName;
+          nameLineOffset = 1;
+          /* v8 ignore stop */
+        }
+      } else {
+        /* v8 ignore start */
+        // First description line has content, use it for the name line
+        const nameLine = descriptionLines[0];
+        result += `${nameLine.initial}${
+          nameLine.delimiter
+        }${nameLine.postDelimiter}${name}${postName}${nameLine.description}`;
+        nameLineOffset = 1;
+        /* v8 ignore stop */
+      }
+    } else {
+      // No description lines, need to construct the name line
+      // Use the same formatting as the tag line
+      result += `${initial}${delimiter}${postDelimiter}${name}${postName}`;
+    }
+  } else {
+    result += name ? `${postType}${name}${postName}` : postType;
+  }
+
+  for (let i = nameLineOffset; i < descriptionLines.length; i++) {
+    const descriptionLine = descriptionLines[i];
+
+    if (i > 0 || nameLineOffset > 0) {
+      result += '\n';
+    }
+
+    result += estreeToString(descriptionLine);
+  }
+
+  return result;
+}
+
+export {estreeToString};

package/src/index.js

@@ -0,0 +1,59 @@
+/* eslint-disable unicorn/no-barrel-files -- Reexports with typedefs */
+/**
+ * An inline tag whose `text` is the unescaped label value.
+ * @typedef {import('./commentParserToESTree.js').JsdocInlineTagNoType & {
+ *   start: number,
+ *   end: number,
+ * }} InlineTag
+ */
+
+/**
+ * @typedef {import('comment-parser').Spec & {
+ *   line?: import('./commentParserToESTree.js').Integer,
+ *   inlineTags: (import('./commentParserToESTree.js').JsdocInlineTagNoType & {
+ *     line?: import('./commentParserToESTree.js').Integer
+ *   })[]
+ * }} JsdocTagWithInline
+ */
+
+/**
+ * Expands on comment-parser's `Block` interface.
+ * @typedef {{
+ *   description: string,
+ *   source: import('comment-parser').Line[],
+ *   problems: import('comment-parser').Problem[],
+ *   tags: JsdocTagWithInline[],
+ *   inlineTags: (import('./commentParserToESTree.js').JsdocInlineTagNoType & {
+ *     line?: import('./commentParserToESTree.js').Integer
+ *   })[]
+ * }} JsdocBlockWithInline
+ */
+
+/* eslint-disable jsdoc/reject-any-type -- API */
+/**
+ * @typedef {{
+ *   preferRawType?: boolean,
+ *   jtppStringificationRules?: (
+ *     node: import('estree').Node, options?: any
+ *   ) => string
+ * }} ESTreeToStringOptions
+ */
+/* eslint-enable jsdoc/reject-any-type -- API */
+
+/**
+ * @callback CommentHandler
+ * @param {string} commentSelector
+ * @param {import('./index.js').JsdocBlockWithInline} jsdoc
+ * @returns {boolean}
+ */
+
+export {visitorKeys as jsdocTypeVisitorKeys} from '@cjser/jsdoc-type-pratt-parser';
+
+export * from '@cjser/jsdoc-type-pratt-parser';
+
+export * from './commentHandler.js';
+export * from './commentParserToESTree.js';
+export * from './estreeToString.js';
+export * from './jsdoccomment.js';
+export * from './parseComment.js';
+export * from './parseInlineTags.js';

package/src/inlineTagEscapes.js

@@ -0,0 +1,73 @@
+/**
+ * @typedef {'pipe' | 'plain' | 'prefix' | 'space'} InlineTagFormat
+ */
+
+/**
+ * Gets the label delimiter for an inline-tag format.
+ * @param {InlineTagFormat} format
+ * @returns {string}
+ */
+function getLabelDelimiter (format) {
+  return format === 'prefix' ? ']' : '}';
+}
+
+/**
+ * Decodes context-specific escape pairs in an inline-tag label.
+ * @param {string} text
+ * @param {InlineTagFormat} format
+ * @returns {string}
+ */
+export function decodeInlineTagText (text, format) {
+  const delimiter = getLabelDelimiter(format);
+  let decoded = '';
+  let idx = 0;
+
+  while (idx < text.length) {
+    const character = text[idx];
+    if (character === '\\') {
+      const nextCharacter = text[idx + 1];
+      if (nextCharacter === '\\' || nextCharacter === delimiter) {
+        decoded += nextCharacter;
+        idx += 2;
+        continue;
+      }
+    }
+    decoded += character;
+    idx++;
+  }
+
+  return decoded;
+}
+
+/**
+ * Minimally encodes an inline-tag label for its output context.
+ * @param {string} text
+ * @param {InlineTagFormat} format
+ * @returns {string}
+ */
+export function encodeInlineTagText (text, format) {
+  const delimiter = getLabelDelimiter(format);
+  let encoded = '';
+
+  for (let idx = 0; idx < text.length; idx++) {
+    const character = text[idx];
+    if (character === delimiter) {
+      encoded += `\\${delimiter}`;
+      continue;
+    }
+
+    if (character === '\\') {
+      const nextCharacter = text[idx + 1];
+      if (
+        [undefined, '\\', delimiter].includes(nextCharacter)
+      ) {
+        encoded += '\\\\';
+        continue;
+      }
+    }
+
+    encoded += character;
+  }
+
+  return encoded;
+}