JavaScript AST Transformer: Adding JSDoc Comments

This challenge asks you to build a JavaScript AST (Abstract Syntax Tree) transformer that automatically adds JSDoc comments to functions. AST transformers are crucial for code analysis and modification, enabling automated refactoring, linting, and code generation. This exercise will help you understand how to traverse and modify the structure of JavaScript code.

Problem Description

You are tasked with creating a JavaScript AST transformer that analyzes a JavaScript code snippet and adds JSDoc comments to all function declarations. The JSDoc comments should include @param tags for each parameter of the function and a @returns tag describing the return value (assume the return value is always void for simplicity). The transformer should modify the AST in place, adding the JSDoc comments as comments preceding the function declaration.

Key Requirements:

• AST Traversal: You must traverse the AST to identify all function declarations (FunctionDeclaration nodes).
• JSDoc Comment Generation: For each function declaration, generate a JSDoc comment string. This string should include:
  • A brief description of the function (e.g., "This function performs some action").
  • @param tags for each parameter, using the parameter name.
  • @returns void tag.
• AST Modification: Insert a BlockStatement containing a single ExpressionStatement with a Literal node (the JSDoc comment string) before the FunctionDeclaration node in the AST.
• Immutability (Important): While modifying the AST in place, ensure your code doesn't introduce unintended side effects or break the AST structure. Use the traverse method provided by @babel/traverse to safely modify the tree.

Expected Behavior:

The transformer should take a JavaScript code snippet (represented as an AST) as input and return the modified AST with JSDoc comments added to all functions. The original code should remain functionally identical, but with the added JSDoc comments.

Edge Cases to Consider:

• Functions nested within other functions.
• Functions with no parameters.
• Code snippets with no functions.
• Invalid JavaScript code (the transformer should handle this gracefully, ideally without crashing). While perfect error handling isn't required, avoid throwing errors if possible.
• Existing comments: The transformer should add the JSDoc comments before any existing comments on the function declaration.

Examples

Example 1:

Input:
[
  {
    "type": "Program",
    "body": [
      {
        "type": "FunctionDeclaration",
        "id": {
          "type": "Identifier",
          "name": "myFunction"
        },
        "params": [
          {
            "type": "Identifier",
            "name": "param1"
          },
          {
            "type": "Identifier",
            "name": "param2"
          }
        ],
        "body": {
          "type": "BlockStatement",
          "body": []
        },
        "leadingComments": [],
        "trailingComments": []
      }
    ]
  }
]

Output:
[
  {
    "type": "Program",
    "body": [
      {
        "type": "BlockStatement",
        "body": [
          {
            "type": "ExpressionStatement",
            "expression": {
              "type": "Literal",
              "value": "/**\n * This function performs some action.\n *\n * @param param1\n * @param param2\n * @returns void\n */"
            }
          }
        ]
      },
      {
        "type": "FunctionDeclaration",
        "id": {
          "type": "Identifier",
          "name": "myFunction"
        },
        "params": [
          {
            "type": "Identifier",
            "name": "param1"
          },
          {
            "type": "Identifier",
            "name": "param2"
          }
        ],
        "body": {
          "type": "BlockStatement",
          "body": []
        },
        "leadingComments": [],
        "trailingComments": []
      }
    ]
  }
]

Explanation: A JSDoc comment is added before the function declaration, including @param tags for param1 and param2 and @returns void.

Example 2:

Input:
[
  {
    "type": "Program",
    "body": [
      {
        "type": "FunctionDeclaration",
        "id": {
          "type": "Identifier",
          "name": "simpleFunction"
        },
        "params": [],
        "body": {
          "type": "BlockStatement",
          "body": []
        },
        "leadingComments": [],
        "trailingComments": []
      }
    ]
  }
]

Output:
[
  {
    "type": "Program",
    "body": [
      {
        "type": "BlockStatement",
        "body": [
          {
            "type": "ExpressionStatement",
            "expression": {
              "type": "Literal",
              "value": "/**\n * This function performs some action.\n * @returns void\n */"
            }
          }
        ]
      },
      {
        "type": "FunctionDeclaration",
        "id": {
          "type": "Identifier",
          "name": "simpleFunction"
        },
        "params": [],
        "body": {
          "type": "BlockStatement",
          "body": []
        },
        "leadingComments": [],
        "trailingComments": []
      }
    ]
  }
]

Explanation: A JSDoc comment is added, but since there are no parameters, no @param tags are included.

Constraints

• Input: The input will always be a valid JavaScript AST object.
• Output: The output must be a modified JavaScript AST object.
• Dependencies: You are allowed to use the @babel/traverse and @babel/types packages. You will need to install them: npm install @babel/traverse @babel/types
• Performance: The transformer should be reasonably efficient. Avoid unnecessary iterations or complex operations. While a hard performance limit isn't imposed, excessively slow transformers will be considered incomplete.

Notes

• You'll need to use @babel/traverse to walk the AST and identify FunctionDeclaration nodes.
• Use @babel/types to create new AST nodes for the JSDoc comments.
• The node.leadingComments property can be used to insert the JSDoc comment before any existing comments.
• Consider using template literals to construct the JSDoc comment string for better readability.
• Focus on correctly modifying the AST structure. The exact formatting of the JSDoc comment is less important than the correct placement and structure within the AST.
• Remember to return the modified AST.