Making flow comments distinguishable on the AST?

[vikr01]

Not sure if this has been posted before, I looked and couldn't find anything in existing issues.

Proposal

Tweak the AST to be able to recognize the difference between a flow comment and runtime code, so that auto-fixing doesn't overwrite flow comments into runtime code.

For example, Prettier has had this issue open for this for quite a while:
prettier/prettier#3493

The "workaround" has been to use babel's parser, which by default doesn't enable the flow comment syntax.

I'm looking to start supporting linting of flow comments just like we do flow typings with babel-eslint by enabling babel's flowComments parser plugin (some discussion in babel/babel#11423). Though, the same issue with prettier would present itself here, and would mean any autofixing rules for types would need to be disabled altogether.

Use case

Currently, the AST doesn't give any information about a node coming from a flow comment. Here's an example of a typing (link) being converted turned into a flow comment (link):

{
  "type": "Program",
  "loc": {
    "source": null,
    "start": {
      "line": 4,
      "column": 0
    },
    "end": {
      "line": 4,
      "column": 17
    }
  },
  "range": [
-    14,
+    18,
-    31
+    35
  ],
  "body": [
    {
      "type": "TypeAlias",
      "loc": {
        "source": null,
        "start": {
          "line": 4,
          "column": 0
        },
        "end": {
          "line": 4,
          "column": 17
        }
      },
      "range": [
-        14,
+        18,
-        31
+        35
      ],
      "id": {
        "type": "Identifier",
        "loc": {
          "source": null,
          "start": {
            "line": 4,
            "column": 5
          },
          "end": {
            "line": 4,
            "column": 8
          }
        },
        "range": [
-          19,
+          23,
-          22
+          26
        ],
        "name": "Bar",
        "typeAnnotation": null,
        "optional": false
      },
      "typeParameters": null,
      "right": {
        "type": "StringLiteralTypeAnnotation",
        "loc": {
          "source": null,
          "start": {
            "line": 4,
            "column": 11
          },
          "end": {
            "line": 4,
            "column": 16
          }
        },
        "range": [
-          25,
+          29,
-          30
+          34
        ],
        "value": "foo",
        "raw": "'foo'"
      }
    }
  ],
  "comments": [
    {
      "type": "Block",
      "loc": {
        "source": null,
        "start": {
          "line": 1,
          "column": 0
        },
        "end": {
          "line": 1,
          "column": 11
        }
      },
      "range": [
        0,
        11
      ],
      "value": " @flow "
    }
  ],
  "errors": []
}

Ideally, there would be something in this AST to tell the difference between flow comments and flow typings, so that linters/auto-fixers can be aware and not overwrite the comments.

I think it would be useful if there was just a FlowComment node that had all nodes within it as child nodes, since auto-fixers generally respect the structure of the AST when rewriting the code.

Example:

{
  "type": "Program",
  "body": [
    {
      "type": "FlowComment",
      "body": [
        {
          "type": "TypeAlias",
          // ...
        },
        // ...
      ],
      // ...
    },
    // ...
  ],
 //  ...
}

Separate to that, I think it would be neat if we had a flag on each node within a flow comment like a boolean flowComment key. This is so that we can actually start creating lint rules specific to flow comments, which would be very cool. For example, a "no-flow-comments" rule or a version of "no-using-comment-vars" that prevents variables declared inside flow comments from being used outside of flow comments.

Example:

{
  "type": "TypeAlias",
  "flowComment": true,
  // ...
}

[thorn0]

Representing these comments in the AST is a difficult or even impossible task. For example, consider the following code. How would you represent it?

/*:: if( */ console.log(1) /*:: ) { console.log(2) } */

(try flow)

[vikr01]

Representing these comments in the AST is a difficult or even impossible task. For example, consider the following code. How would you represent it?

/*:: if( */ console.log(1) /*:: ) { console.log(2) } */

(try flow)

Oof, I didn't even realize it was possible to wrap code inside of flow comment blocks and flow reads it all the same.