hermes-transform 0.28.0 → 0.29.0

package/dist/src/transform/comments/comments.js

@@ -0,0 +1,308 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CommentPlacement = void 0;
+exports.addComment = addComment;
+exports.appendCommentToSource = appendCommentToSource;
+exports.attachComments = attachComments;
+exports.cloneComment = cloneComment;
+exports.cloneCommentWithMarkers = cloneCommentWithMarkers;
+exports.cloneCommentsToNewNode = cloneCommentsToNewNode;
+exports.cloneJSDocCommentsToNewNode = cloneJSDocCommentsToNewNode;
+exports.getCommentsForNode = getCommentsForNode;
+exports.getLeadingCommentsForNode = getLeadingCommentsForNode;
+exports.getTrailingCommentsForNode = getTrailingCommentsForNode;
+exports.isAttachedComment = isAttachedComment;
+exports.isLeadingComment = isLeadingComment;
+exports.isTrailingComment = isTrailingComment;
+exports.makeCommentOwnLine = makeCommentOwnLine;
+exports.moveCommentsToNewNode = moveCommentsToNewNode;
+exports.mutateESTreeASTCommentsForPrettier = mutateESTreeASTCommentsForPrettier;
+exports.setCommentsOnNode = setCommentsOnNode;
+
+var _comments = require("./prettier/main/comments");
+
+var _loc = require("./prettier/language-js/loc");
+
+var _printerEstree = _interopRequireDefault(require("./prettier/language-js/printer-estree"));
+
+var _util = require("./prettier/common/util");
+
+var _hermesEstree = require("hermes-estree");
+
+var _os = require("os");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * 
+ * @format
+ */
+// $FlowExpectedError[untyped-import]
+// $FlowExpectedError[untyped-import]
+// $FlowExpectedError[untyped-import]
+const CommentPlacement = require("flow-enums-runtime").Mirrored(["LEADING_OWN_LINE", "LEADING_INLINE", "TRAILING_OWN_LINE", "TRAILING_INLINE"]);
+
+exports.CommentPlacement = CommentPlacement;
+
+function attachComments(comments, ast, text) {
+  (0, _comments.attach)(comments, ast, text, {
+    locStart: _loc.locStart,
+    locEnd: _loc.locEnd,
+    printer: _printerEstree.default
+  });
+}
+
+function mutateESTreeASTCommentsForPrettier(program, text) {
+  let code = text; // we need to delete the comments prop or else prettier will do
+  // its own attachment pass after the mutation and duplicate the
+  // comments on each node, borking the output
+  // $FlowExpectedError[cannot-write]
+
+  delete program.comments; // The docblock comment is never attached to any AST nodes, since its technically
+  // attached to the program. However this is specific to our AST and in order for
+  // prettier to correctly print it we need to attach it to the first node in the
+  // program body.
+
+  if (program.docblock != null && program.docblock.comment != null) {
+    const docblockComment = program.docblock.comment;
+    const isDocblockCommentNew = !isAttachedComment(docblockComment);
+
+    if (isDocblockCommentNew) {
+      // $FlowExpectedError[prop-missing]
+      docblockComment.printed = false; // $FlowExpectedError[prop-missing]
+
+      docblockComment.leading = true; // $FlowExpectedError[prop-missing]
+
+      docblockComment.trailing = false;
+    } // If we have a first node in the program body, attach the comment to that
+    // otherwise set it on the program.
+
+
+    if (program.body.length > 0) {
+      const firstStatement = program.body[0];
+      const leadingComments = getLeadingCommentsForNode(firstStatement);
+
+      if (!leadingComments.includes(docblockComment)) {
+        setCommentsOnNode(firstStatement, [docblockComment, ...getCommentsForNode(firstStatement)]);
+
+        if (isDocblockCommentNew) {
+          // Add markers to the code block to ensure docblock comment is printed on its
+          // own line.
+          code = makeCommentOwnLine(code, docblockComment);
+        }
+      }
+    } else {
+      setCommentsOnNode(program, [docblockComment]);
+    }
+  } // Should not be needed anymore
+  // $FlowExpectedError[cannot-write]
+
+
+  delete program.docblock;
+  return code;
+}
+
+function moveCommentsToNewNode(oldNode, newNode) {
+  setCommentsOnNode(newNode, getCommentsForNode(oldNode));
+  setCommentsOnNode(oldNode, []);
+}
+
+function cloneCommentsToNewNode(oldNode, newNode) {
+  setCommentsOnNode(newNode, getCommentsForNode(oldNode).map(comment => cloneCommentWithMarkers(comment)));
+}
+
+function cloneJSDocCommentsToNewNode(oldNode, newNode) {
+  const comments = getCommentsForNode(oldNode).filter(comment => {
+    return (0, _hermesEstree.isBlockComment)(comment) && // JSDoc comments always start with an extra asterisk
+    comment.value.startsWith('*');
+  });
+  setCommentsOnNode(newNode, [...getCommentsForNode(newNode), ...comments.map(cloneCommentWithMarkers)]);
+}
+
+function setCommentsOnNode(node, comments) {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  node.comments = comments;
+}
+
+function getCommentsForNode(node) {
+  var _node$comments;
+
+  // $FlowExpectedError - this property is secretly added by prettier.
+  return (_node$comments = node.comments) != null ? _node$comments : [];
+}
+
+function isAttachedComment(comment) {
+  // Prettier adds this property to comments that have been attached.
+  // $FlowExpectedError[prop-missing] - this property is secretly added by prettier.
+  return comment.printed === false;
+}
+
+function isLeadingComment(comment) {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  return comment.leading === true;
+}
+
+function isTrailingComment(comment) {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  return comment.trailing === true;
+}
+
+function getLeadingCommentsForNode(node) {
+  return getCommentsForNode(node).filter(isLeadingComment);
+}
+
+function getTrailingCommentsForNode(node) {
+  return getCommentsForNode(node).filter(isTrailingComment);
+}
+
+function addComment(node, comment, placement) {
+  switch (placement) {
+    case CommentPlacement.LEADING_OWN_LINE:
+    case CommentPlacement.LEADING_INLINE:
+      {
+        (0, _util.addLeadingComment)(node, comment);
+        break;
+      }
+
+    case CommentPlacement.TRAILING_OWN_LINE:
+    case CommentPlacement.TRAILING_INLINE:
+      {
+        (0, _util.addTrailingComment)(node, comment);
+        break;
+      }
+  }
+}
+
+function cloneComment(comment) {
+  // $FlowExpectedError[incompatible-return]
+  return {
+    type: comment.type,
+    value: comment.value,
+    loc: comment.loc,
+    range: comment.range
+  };
+}
+
+function cloneCommentWithMarkers(comment) {
+  // $FlowExpectedError[incompatible-return]
+  return {
+    type: comment.type,
+    value: comment.value,
+    loc: comment.loc,
+    range: comment.range,
+    leading: isLeadingComment(comment),
+    trailing: isTrailingComment(comment)
+  };
+}
+
+function getFirstNewlineIndex(code) {
+  return code.search(/\r\n|\n|\r/);
+}
+
+function getFirstNonWhitespaceIndex(code) {
+  return code.search(/\S/);
+}
+
+function makeCommentOwnLine(code, comment) {
+  let newCode = code; // Since we always want a line break we need to ensure a newline is found when
+  // searching out from either side of the comment range.
+
+  let firstNewline = getFirstNewlineIndex(code);
+
+  if (firstNewline === -1) {
+    // No newline in file, lets add one.
+    newCode += _os.EOL;
+    firstNewline = newCode.length;
+  } // Prettier only uses these ranges for detecting whitespace, so this nonsensical
+  // range is safe.
+  // $FlowExpectedError[cannot-write]
+
+
+  comment.range = [firstNewline + 1, firstNewline];
+  return newCode;
+}
+
+function appendCommentToSource(code, comment, placement) {
+  let newCode = code;
+
+  switch (comment.type) {
+    case 'Block':
+      {
+        // Prettier decides if a newline is necessary between the comment and its node by looking
+        // to see if a newline seperates them in the source text. We can trick prettier into
+        // formatting how we want for new comments by placing the range such that a newline
+        // will (OWN_LINE) or will not (INLINE) be found when searching from the specified range
+        // position.
+        switch (placement) {
+          case CommentPlacement.LEADING_OWN_LINE:
+          case CommentPlacement.TRAILING_OWN_LINE:
+            {
+              newCode = makeCommentOwnLine(code, comment);
+              break;
+            }
+
+          case CommentPlacement.LEADING_INLINE:
+          case CommentPlacement.TRAILING_INLINE:
+            {
+              // Since we don't want a line break we need to ensure a non whitespace char is
+              // always found before a newline when searching out from either side of the
+              // comment range.
+              let firstNonWhitespace = getFirstNonWhitespaceIndex(code);
+
+              if (firstNonWhitespace === -1) {
+                // No non whitespace chars in file, lets add an identifiable statement for prettier to find.
+                newCode += '$FORCE_INLINE_ON_EMPTY_FILE_TOKEN$;';
+                firstNonWhitespace = newCode.length;
+                break;
+              } // $FlowExpectedError[cannot-write]
+
+
+              comment.range = [firstNonWhitespace + 1, firstNonWhitespace];
+              break;
+            }
+        }
+
+        break;
+      }
+
+    case 'Line':
+      {
+        // For `Line` comments prettier slices comments directly from the source code when printing
+        // https://github.com/prettier/prettier/blob/5f0ee39fa03532c85bd1c35291450fe7ac3667b3/src/language-js/print/comment.js#L15-L20
+        // this means that we need to have any appended comments directly in the
+        // source code or else prettier will slice nothing and bork up the transform
+        const commentText = `//${comment.value}`;
+        const lastChar = newCode[newCode.length - 1];
+
+        if (lastChar !== '\n' && lastChar !== '\r') {
+          newCode += _os.EOL;
+        } // Line comments cannot be inline before a node so we only place trailing Line comments inline.
+
+
+        if (placement === CommentPlacement.TRAILING_INLINE) {
+          // Prettier determines an "end of line" comment by walking backwards from
+          // the comment start range through the source code to see if it finds a non
+          // newline token. In order to trick prettier for new comments we need to
+          // insert fake source code for it to find.
+          newCode += '$FORCE_END_OF_LINE_COMMENT_TOKEN$;';
+        }
+
+        const start = newCode.length;
+        newCode += commentText;
+        const end = newCode.length; // $FlowExpectedError[cannot-write]
+
+        comment.range = [start, end];
+        break;
+      }
+  }
+
+  return newCode;
+}

package/dist/src/transform/comments/prettier/common/util.js

@@ -0,0 +1,364 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+'use strict';
+
+const stringWidth = require('string-width');
+
+const getLast = require('../utils/get-last.js');
+
+const notAsciiRegex = /[^\x20-\x7F]/;
+/**
+ * @typedef {{backwards?: boolean}} SkipOptions
+ */
+
+/**
+ * @param {string | RegExp} chars
+ * @returns {(text: string, index: number | false, opts?: SkipOptions) => number | false}
+ */
+
+function skip(chars) {
+  return (text, index, opts) => {
+    const backwards = opts && opts.backwards; // Allow `skip` functions to be threaded together without having
+    // to check for failures (did someone say monads?).
+
+    /* istanbul ignore next */
+
+    if (index === false) {
+      return false;
+    }
+
+    const {
+      length
+    } = text;
+    let cursor = index;
+
+    while (cursor >= 0 && cursor < length) {
+      const c = text.charAt(cursor);
+
+      if (chars instanceof RegExp) {
+        if (!chars.test(c)) {
+          return cursor;
+        }
+      } else if (!chars.includes(c)) {
+        return cursor;
+      }
+
+      backwards ? cursor-- : cursor++;
+    }
+
+    if (cursor === -1 || cursor === length) {
+      // If we reached the beginning or end of the file, return the
+      // out-of-bounds cursor. It's up to the caller to handle this
+      // correctly. We don't want to indicate `false` though if it
+      // actually skipped valid characters.
+      return cursor;
+    }
+
+    return false;
+  };
+}
+/**
+ * @type {(text: string, index: number | false, opts?: SkipOptions) => number | false}
+ */
+
+
+const skipWhitespace = skip(/\s/);
+/**
+ * @type {(text: string, index: number | false, opts?: SkipOptions) => number | false}
+ */
+
+const skipSpaces = skip(' \t');
+/**
+ * @type {(text: string, index: number | false, opts?: SkipOptions) => number | false}
+ */
+
+const skipToLineEnd = skip(',; \t');
+/**
+ * @type {(text: string, index: number | false, opts?: SkipOptions) => number | false}
+ */
+
+const skipEverythingButNewLine = skip(/[^\n\r]/);
+/**
+ * @param {string} text
+ * @param {number | false} index
+ * @returns {number | false}
+ */
+
+function skipInlineComment(text, index) {
+  /* istanbul ignore next */
+  if (index === false) {
+    return false;
+  }
+
+  if (text.charAt(index) === '/' && text.charAt(index + 1) === '*') {
+    for (let i = index + 2; i < text.length; ++i) {
+      if (text.charAt(i) === '*' && text.charAt(i + 1) === '/') {
+        return i + 2;
+      }
+    }
+  }
+
+  return index;
+}
+/**
+ * @param {string} text
+ * @param {number | false} index
+ * @returns {number | false}
+ */
+
+
+function skipTrailingComment(text, index) {
+  /* istanbul ignore next */
+  if (index === false) {
+    return false;
+  }
+
+  if (text.charAt(index) === '/' && text.charAt(index + 1) === '/') {
+    return skipEverythingButNewLine(text, index);
+  }
+
+  return index;
+} // This one doesn't use the above helper function because it wants to
+// test \r\n in order and `skip` doesn't support ordering and we only
+// want to skip one newline. It's simple to implement.
+
+/**
+ * @param {string} text
+ * @param {number | false} index
+ * @param {SkipOptions=} opts
+ * @returns {number | false}
+ */
+
+
+function skipNewline(text, index, opts) {
+  const backwards = opts && opts.backwards;
+
+  if (index === false) {
+    return false;
+  }
+
+  const atIndex = text.charAt(index);
+
+  if (backwards) {
+    // We already replace `\r\n` with `\n` before parsing
+
+    /* istanbul ignore next */
+    if (text.charAt(index - 1) === '\r' && atIndex === '\n') {
+      return index - 2;
+    }
+
+    if (atIndex === '\n' || atIndex === '\r' || atIndex === '\u2028' || atIndex === '\u2029') {
+      return index - 1;
+    }
+  } else {
+    // We already replace `\r\n` with `\n` before parsing
+
+    /* istanbul ignore next */
+    if (atIndex === '\r' && text.charAt(index + 1) === '\n') {
+      return index + 2;
+    }
+
+    if (atIndex === '\n' || atIndex === '\r' || atIndex === '\u2028' || atIndex === '\u2029') {
+      return index + 1;
+    }
+  }
+
+  return index;
+}
+/**
+ * @param {string} text
+ * @param {number} index
+ * @param {SkipOptions=} opts
+ * @returns {boolean}
+ */
+
+
+function hasNewline(text, index, opts = {}) {
+  const idx = skipSpaces(text, opts.backwards ? index - 1 : index, opts);
+  const idx2 = skipNewline(text, idx, opts);
+  return idx !== idx2;
+}
+/**
+ * @param {string} text
+ * @param {number} start
+ * @param {number} end
+ * @returns {boolean}
+ */
+
+
+function hasNewlineInRange(text, start, end) {
+  for (let i = start; i < end; ++i) {
+    if (text.charAt(i) === '\n') {
+      return true;
+    }
+  }
+
+  return false;
+}
+/**
+ * @param {string} text
+ * @param {number} index
+ * @returns {boolean}
+ */
+
+
+function isNextLineEmptyAfterIndex(text, index) {
+  /** @type {number | false} */
+  let oldIdx = null;
+  /** @type {number | false} */
+
+  let idx = index;
+
+  while (idx !== oldIdx) {
+    // We need to skip all the potential trailing inline comments
+    oldIdx = idx;
+    idx = skipToLineEnd(text, idx);
+    idx = skipInlineComment(text, idx);
+    idx = skipSpaces(text, idx);
+  }
+
+  idx = skipTrailingComment(text, idx);
+  idx = skipNewline(text, idx);
+  return idx !== false && hasNewline(text, idx);
+}
+/**
+ * @param {string} text
+ * @param {number} idx
+ * @returns {number | false}
+ */
+
+
+function getNextNonSpaceNonCommentCharacterIndexWithStartIndex(text, idx) {
+  /** @type {number | false} */
+  let oldIdx = null;
+  /** @type {number | false} */
+
+  let nextIdx = idx;
+
+  while (nextIdx !== oldIdx) {
+    oldIdx = nextIdx;
+    nextIdx = skipSpaces(text, nextIdx);
+    nextIdx = skipInlineComment(text, nextIdx);
+    nextIdx = skipTrailingComment(text, nextIdx);
+    nextIdx = skipNewline(text, nextIdx);
+  }
+
+  return nextIdx;
+}
+/**
+ * @template N
+ * @param {string} text
+ * @param {N} node
+ * @param {(node: N) => number} locEnd
+ * @returns {number | false}
+ */
+
+
+function getNextNonSpaceNonCommentCharacterIndex(text, node, locEnd) {
+  return getNextNonSpaceNonCommentCharacterIndexWithStartIndex(text, locEnd(node));
+}
+/**
+ * @template N
+ * @param {string} text
+ * @param {N} node
+ * @param {(node: N) => number} locEnd
+ * @returns {string}
+ */
+
+
+function getNextNonSpaceNonCommentCharacter(text, node, locEnd) {
+  return text.charAt( // @ts-expect-error => TBD: can return false, should we define a fallback?
+  getNextNonSpaceNonCommentCharacterIndex(text, node, locEnd));
+}
+/**
+ * @param {string} text
+ * @returns {number}
+ */
+
+
+function getStringWidth(text) {
+  if (!text) {
+    return 0;
+  } // shortcut to avoid needless string `RegExp`s, replacements, and allocations within `string-width`
+
+
+  if (!notAsciiRegex.test(text)) {
+    return text.length;
+  }
+
+  return stringWidth(text);
+}
+
+function addCommentHelper(node, comment) {
+  const comments = node.comments || (node.comments = []);
+  comments.push(comment);
+  comment.printed = false;
+  comment.nodeDescription = describeNodeForDebugging(node);
+}
+
+function addLeadingComment(node, comment) {
+  comment.leading = true;
+  comment.trailing = false;
+  addCommentHelper(node, comment);
+}
+
+function addDanglingComment(node, comment, marker) {
+  comment.leading = false;
+  comment.trailing = false;
+
+  if (marker) {
+    comment.marker = marker;
+  }
+
+  addCommentHelper(node, comment);
+}
+
+function addTrailingComment(node, comment) {
+  comment.leading = false;
+  comment.trailing = true;
+  addCommentHelper(node, comment);
+}
+/**
+ * @param {any} object
+ * @returns {object is Array<any>}
+ */
+
+
+function isNonEmptyArray(object) {
+  return Array.isArray(object) && object.length > 0;
+}
+
+function describeNodeForDebugging(node) {
+  const nodeType = node.type || node.kind || '(unknown type)';
+  let nodeName = String(node.name || node.id && (typeof node.id === 'object' ? node.id.name : node.id) || node.key && (typeof node.key === 'object' ? node.key.name : node.key) || node.value && (typeof node.value === 'object' ? '' : String(node.value)) || node.operator || '');
+
+  if (nodeName.length > 20) {
+    nodeName = nodeName.slice(0, 19) + '…';
+  }
+
+  return nodeType + (nodeName ? ' ' + nodeName : '');
+}
+
+module.exports = {
+  getStringWidth,
+  getLast,
+  getNextNonSpaceNonCommentCharacterIndexWithStartIndex,
+  getNextNonSpaceNonCommentCharacterIndex,
+  getNextNonSpaceNonCommentCharacter,
+  skipWhitespace,
+  skipSpaces,
+  skipNewline,
+  isNextLineEmptyAfterIndex,
+  hasNewline,
+  hasNewlineInRange,
+  addLeadingComment,
+  addDanglingComment,
+  addTrailingComment,
+  isNonEmptyArray
+};