Align JS-side AST with standard for TypeScript

[overlookmotel]

Our AST on JS side (via oxc-parser NPM package) is now aligned with ESTree standard for JS syntax. We have conformance tests which ensure our AST is exactly the same as Acorn's AST for all Test262 test cases which Acorn can parse.

However, we do not yet guarantee that our AST for TypeScript types is aligned with any particular standard.

TS-ESLint's parser seems like the obvious target.

Achieving alignment

Recently there have been various PRs to align parts of the AST with TS-ESLint.

In my opinion, it'd be preferable if we took a more systematic approach, using a conformance suite. This will ensure:

• We don't miss anything, and can confidently assert our complete alignment with TS-ESLint.
• We don't break anything in future.
• While making changes to align one type, we don't inadvertently break another.

This methodology proved successful while working on ESTree comatibility. Once we had the conformance suite working, we got to 99% passing within a few days!

I suggest we adopt same approach as I've outlined in #9703, with the target snapshots generated in and committed to acorn-test262 repo. We can:

• Use all the test cases in https://github.com/microsoft/TypeScript/tree/main/tests/cases/conformance and https://github.com/microsoft/TypeScript/tree/main/tests/cases/compiler.
• Parse all these cases with TS-ESLint parser, convert the resulting ASTs to JSON, and commit those JSON files to the repo.

How

Wherever possible, it's preferable to use the DSL (domain specific language) provided by #[estree] attributes on AST types to control how the AST gets converted e.g. #[estree(flatten)], #[estree(rename = "...")], #[estree(append_to = "...")].

We can also use custom converters #[estree(via = ...)] where necessary, but the less we have to resort to that, the better.

Conflicts between ESTree and TS-ESLint

It's possible that we'll run into cases where Acorn and TS-ESLint produce a different AST for some JS syntax. If so, that'll be problematic. Ideally we want a single AST shape which is compatible with both ESTree and TS-ESLint.

If we do find such cases, I suggest that we just skip them initially. Once we have everything else passing, we can see how broad a problem this is, and figure out how best to deal with it.

Raw transfer

I suggest that in the inital alignment effort, we don't worry about raw transfer.

Let's only adapt the AST that Oxc generates as JSON via ESTree trait. This will be simpler to do, and will get us to the finish line faster.

Only once we have all the tests passing, we can then work on getting the AST generated by raw transfer aligned too. This is generally much easier once you have a working ESTree impl to translate from.

JSX

See #9703. I suggest we do JSX first before TS.

[overlookmotel]

cc @ArnaudBarre @hi-ogawa

[ArnaudBarre]

I think you should target TS-ESLint for anything non supported by acorn, this will simplify the setup. JSX is small enough so that it will probably not conflict, but today most JSX code is TSX so IMO I think you can avoid the intermediary step.
Also TS-ESLint adopt JS features faster than acorn (the these two small diff I found, on top of acorn not yet handling decorators or import assertions) so IMO you should only target one popular parser (Babel would be a valid choice also)

[overlookmotel]

#9774 implements a TS conformance suite.

Continuing the conversation from that PR about current state of our conformance...

@hi-ogawa said:

Current result Positive Passed: 32/10725 (0.30%) 😢

Oh dear! Well, we had a similar result when we started on ESTree conformance, and within a few days we were at 99%. Maybe it'll be the same this time, inshallah.

But...

maybe keys are ordered alphabetically

In Literal nodes for numbers, TS-ESLint has the raw field before value. That also matches the pattern of alphabetical order that you noticed.

The order of keys doesn't really matter. What does matter is that it's consistent, to make operating on the objects in JS code efficient, as consistent object shapes allow JS engines to monomorphize functions that operate on those objects.

The other advantage of testing for correct field order is that conformance tests can compare the JSON produced by our serializer directly to the snapshotted JSON, with a simple string comparison. This is much faster than using serde to parse both JSONs to serde::Values, and comparing those structures. Before I made the switch to direct JSON string comparison, the conformance tests were impractically slow to run on CI.

I can see 2 possible ways forward:

1. Alter conformance tester to not be sensitive to field order, at least for now. We could disable testing TS conformance on CI, while we work on getting the AST aligned, and then deal with field order later.

2. Alter the AST in acorn-test262 before serializing to JSON. We'd re-order fields to be same order as ESTree (Acorn), with additional TS fields after that. To avoid having to add loads of #[estree(field_order(...))] attributes to AST types, we could alter the codegen in oxc_ast_tools to automatically put #[ts] fields last.

Perhaps (1) is a good place to start, and then we do (2) later on?

typescript-eslint parser uses undefined instead of null for optional ts-specific field

That's problematic. We could match that behavior in raw transfer without any perf hit, but obviously we can't when transferring the AST via JSON. We'd have to add a "fixup" pass on JS side to convert null to undefined. I imagine that'd be costly.

I think we need to keep the JSON-based transfer method alive for the foreseeable future. Raw transfer is experimental, and quite possible it has show-stopper bugs. We've already found it doesn't work on Node 20 or Bun, and we've not got it working on WASM yet.

I would also be loathe to remove empty TS-specific fields entirely in JS-side AST. That'd be a big perf hit for the consumer, as it'd result in variable object shapes.

I'd suggest the best starting point on this one is to modify the AST in acorn-test262 to convert all undefineds to nulls, prior to converting to JSON.

But does null vs undefined matter anyway? Will it affect downstream tools if we just go with null?

[overlookmotel]

@hi-ogawa Do you have write access to acorn-estree repo? If so, feel free to make changes there if required and merge your own PRs. I'm going to be away from keyboard until Monday, and don't want to block your progress if you're working during that time.

[hi-ogawa]

@overlookmotel Yes, I saw a green merge button myself, so I should be able to push it. 👍

[ArnaudBarre]

You will have pre-processing to do anyway to convert TS-ESLint location to start/end. You could also do the null/undefined change during that process.
Personally for now I've done the diff in pure JS, to also have false, null, undefined and [] be considered equivalent, handle bigint non json serializable and don't throw on nullable keys from one or the other.

[overlookmotel]

Just to clarify one point:

Alter conformance tester to not be sensitive to field order, at least for now.

I mean alter conformance tester for TypeScript only. We have succeeded in getting field order aligned with Acorn (and I made some PRs on Acorn acornjs/acorn#1347 acornjs/acorn#1346 to make Acorn align with us!), so would be ideal not to accidentally regress that.

[armano2]

AST of ts-eslint should be 100% aligned with estree (extended), but there is sometimes differences when new js features are added (stage 3) and there is small period of time where AST may differ
ts-eslint also does alignment check with @babel/eslint to ensure that consistency

• https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/ast-spec/tests/util/serializers/Node.ts
• https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/ast-spec/src/declaration/ClassDeclaration/fixtures/extends/snapshots/1-TSESTree-AST.shot
• https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/ast-spec/src/declaration/ClassDeclaration/fixtures/extends/snapshots/3-Babel-AST.shot

But does null vs undefined matter anyway? Will it affect downstream tools if we just go with null?

yes to my knowledge there is few cases where null has actual meaning in estree but there is technically no difference in null | undefined as far as estree is concerned outside of semantics and depending what parser you use acron/babel/ts-eslint/esprima "nullish" value may be different

https://github.com/estree/estree/blob/master/es2015.md#expressions

eg.

[,2]
/// elements: [null, Literal]

https://typescript-eslint.io/play/#ts=5.7.3&showAST=es&fileType=.tsx&code=MYewdgzgLgBAHjAvDA2gGgEwF0g&eslintrc=N4KABGBEBOCuA2BTAzpAXGYBfEWg&tsconfig=N4KABGBEDGD2C2AHAlgGwKYCcDyiAuysAdgM6QBcYoEEkJemy0eAcgK6qoDCAFutAGsylBm3TgwAXxCSgA&tokens=false

---

additionally ts-eslint adds empty array's and defaults "flags" to false and eg. babel does not always do it for ts specific fields

[overlookmotel]

To avoid having to add loads of #[estree(field_order(...))] attributes to AST types, we could alter the codegen in oxc_ast_tools to automatically put #[ts] fields last.

I'm going to do this part now.

[hi-ogawa]

2. Alter the AST in acorn-test262 before serializing to JSON. We'd re-order fields to be same order as ESTree (Acorn), with additional TS fields after that.

I'm thinking about this, but to reorder this, we need to know acorn's order in js script of acorn-test262. Is there any easy-to-use format of estree spec providing this data? Either generating our own from ast tools or somehow extracting it from markdown https://github.com/estree/estree or dts https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/estree/index.d.ts?

For now I went with 2st option of normalizing oxc output #9813.

[overlookmotel]

To avoid having to add loads of #[estree(field_order(...))] attributes to AST types, we could alter the codegen in oxc_ast_tools to automatically put #[ts] fields last.

This is now done. It actually affected very few types. #9820

For now I went with 2st option of normalizing oxc output #9813.

OK great. Yes, probably easiest to get content aligned first before we worry about field order.

Maybe the slow speed I noticed previously was from generating diffs for mismatches, rather than the serde deserialization.

I'm thinking about this, but to reorder this, we need to know acorn's order in js script of acorn-test262. Is there any easy-to-use format of estree spec providing this data? Either generating our own from ast tools or somehow extracting it from markdown https://github.com/estree/estree or dts https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/estree/index.d.ts?

Yes. I've written something to output a list of types with their field order, based on Oxc's AST schema: overlookmotel/estree-field-orders branch + oxc-project/acorn-test262#11

We can do that whenever we're ready.

Right now it's not perfect, because there are some types which exist in our AST which don't exist in TS-ESLint's (and probably vice-versa).

[overlookmotel]

Thanks for the feedback.

AST of ts-eslint should be 100% aligned with estree (extended), but there is sometimes differences when new js features are added (stage 3) and there is small period of time where AST may differ ts-eslint also does alignment check with @babel/eslint to ensure that consistency

This is great to hear. Hopefully we won't have trouble with the ESTree-compatible and TSESLint-compatible ASTs diverging from each other (apart from, obviously, the TS AST having more fields e.g. typeAnnotation, and additional types for those fields).

yes to my knowledge there is few cases where null has actual meaning in estree but there is technically no difference in null | undefined as far as estree is concerned outside of semantics and depending what parser you use acron/babel/ts-eslint/esprima "nullish" value may be different

https://github.com/estree/estree/blob/master/es2015.md#expressions

eg.

[,2]
/// elements: [null, Literal]

We do handle that one correctly.

I think our best starting point is to treat null and undefined as equivalent ("undefined" meaning a field that exists and has the value undefined, as opposed to a field which isn't present at all).

additionally ts-eslint adds empty array's and defaults "flags" to false and eg. babel does not always do it for ts specific fields

Interesting. Babel is a whole other thing, though. Babel's AST is quite different from ESTree, and we're not seeking to replicate its AST (though we might offer that as an option later on, if there's a demand for it).

[hi-ogawa]

If anyone is interested in helping out this, here is my workflow to understand estree mismatches:

# this runs full estree conformance and updates estree_xxx.snap
# but doesn't generate diff
cargo run -p oxc_coverage -- estree

# SAVE_DIFF=true to save diff files in tasks/coverage/acorn-test262-diff
# saving many files is too slow, so using --filter is recommended
SAVE_DIFF=true cargo run -p oxc_coverage -- estree --filter compiler/2dArray

# also you can use `just example parser` for any file to dump ast output
just example parser --estree test.ts

And this is an example diff, which shows Identifier and thisParam is off currently.

tasks/coverage/acorn-test262-diff/typescript/tests/cases/compiler/2dArrays.diff

@@ -20,10 +20,7 @@
         "type": "Identifier",
         "start": 6,
         "end": 10,
-        "decorators": [],
-        "name": "Cell",
-        "optional": false,
-        "typeAnnotation": null
+        "name": "Cell"
       },
       "implements": [],
       "superClass": null,
@@ -53,10 +50,7 @@
               "type": "Identifier",
               "start": 33,
               "end": 39,
-              "decorators": [],
-              "name": "isSunk",
-              "optional": false,
-              "typeAnnotation": null
+              "name": "isSunk"
             },
             "optional": false,
             "override": false,
@@ -82,10 +76,7 @@
         "type": "Identifier",
         "start": 22,
         "end": 26,
-        "decorators": [],
-        "name": "Ship",
-        "optional": false,
-        "typeAnnotation": null
+        "name": "Ship"
       },
       "implements": [],
       "superClass": null,
@@ -115,10 +106,7 @@
               "type": "Identifier",
               "start": 71,
               "end": 76,
-              "decorators": [],
-              "name": "ships",
-              "optional": false,
-              "typeAnnotation": null
+              "name": "ships"
             },
             "optional": false,
             "override": false,
@@ -141,10 +129,7 @@
                     "type": "Identifier",
                     "start": 78,
                     "end": 82,
-                    "decorators": [],
-                    "name": "Ship",
-                    "optional": false,
-                    "typeAnnotation": null
+                    "name": "Ship"
                   }
                 }
               }
@@ -164,10 +149,7 @@
               "type": "Identifier",
               "start": 90,
               "end": 95,
-              "decorators": [],
-              "name": "cells",
-              "optional": false,
-              "typeAnnotation": null
+              "name": "cells"
             },
             "optional": false,
             "override": false,
@@ -190,10 +172,7 @@
                     "type": "Identifier",
                     "start": 97,
                     "end": 101,
-                    "decorators": [],
-                    "name": "Cell",
-                    "optional": false,
-                    "typeAnnotation": null
+                    "name": "Cell"
                   }
                 }
               }
@@ -211,10 +190,7 @@
               "type": "Identifier",
               "start": 118,
               "end": 130,
-              "decorators": [],
-              "name": "allShipsSunk",
-              "optional": false,
-              "typeAnnotation": null
+              "name": "allShipsSunk"
             },
             "kind": "method",
             "optional": false,
@@ -262,20 +238,14 @@
                                     "type": "Identifier",
                                     "start": 191,
                                     "end": 194,
-                                    "decorators": [],
-                                    "name": "val",
-                                    "optional": false,
-                                    "typeAnnotation": null
+                                    "name": "val"
                                   },
                                   "optional": false,
                                   "property": {
                                     "type": "Identifier",
                                     "start": 195,
                                     "end": 201,
-                                    "decorators": [],
-                                    "name": "isSunk",
-                                    "optional": false,
-                                    "typeAnnotation": null
+                                    "name": "isSunk"
                                   }
                                 }
                               }
@@ -290,13 +260,17 @@
                               "type": "Identifier",
                               "start": 177,
                               "end": 180,
+                              "accessibility": null,
                               "decorators": [],
                               "name": "val",
                               "optional": false,
+                              "override": false,
+                              "readonly": false,
                               "typeAnnotation": null
                             }
                           ],
                           "returnType": null,
+                          "thisParam": null,
                           "typeParameters": null
                         }
                       ],
@@ -320,10 +294,7 @@
                             "type": "Identifier",
                             "start": 155,
                             "end": 160,
-                            "decorators": [],
-                            "name": "ships",
-                            "optional": false,
-                            "typeAnnotation": null
+                            "name": "ships"
                           }
                         },
                         "optional": false,
@@ -331,10 +302,7 @@
                           "type": "Identifier",
                           "start": 161,
                           "end": 166,
-                          "decorators": [],
-                          "name": "every",
-                          "optional": false,
-                          "typeAnnotation": null
+                          "name": "every"
                         }
                       },
                       "optional": false,
@@ -349,6 +317,7 @@
               "id": null,
               "params": [],
               "returnType": null,
+              "thisParam": null,
               "typeParameters": null
             }
           }
@@ -360,10 +329,7 @@
         "type": "Identifier",
         "start": 59,
         "end": 64,
-        "decorators": [],
-        "name": "Board",
-        "optional": false,
-        "typeAnnotation": null
+        "name": "Board"
       },
       "implements": [],
       "superClass": null,

Original ts source file is found in tasks/coverage/typescript/tests/cases/compiler/2dArrays.ts and a reference estree output is found in tasks/coverage/acorn-test262/test-typescript/tests/cases/compiler/2dArrays.ts.md.

[leaysgur]

I agree with that direction.

Regarding TS ASTs, it feels difficult to determine the criteria for what is a parse error, how much incomplete AST is acceptable, etc seems vague...

AST Parsed : 6489/6493 (99.94%)
Positive Passed: 6458/6493 (99.46%)

Let's focus on these 35 cases! 🏁

(First, I'll recreate the TODO list later.)

[overlookmotel]

I don't think we need to worry about the serde_json errors. They're all related to deficiencies in serde_json, and will go away once we switch to comparing the 2 ASTs as JSON strings. #10660 removes these errors from snapshot.

"Expect to Parse" is a bit more complicated. Some of these should pass, but the bugs aren't related to ESTree conversion - cause is either in parser or in conformance tester. #10661 skips 5 of them (out of 6) where the case is already listed as a fail in parser conformance snapshot.

I'm going to go through the mismatches now. These are the ones that are related to ESTree conversion, and that we do need to fix.

[overlookmotel]

Oh man these span mismatches are hard! I'm having trouble even figuring out which node is different, because ASTs produced by even a single statement are quite large with multiple nodes called TSTypeAnnotation!

I've opened an issue about with vs assert (typescript-eslint/typescript-eslint#11114) and in meantime have replicated this weird behavior in #10681.

The mismatches we have left:

• parser: JSX parsing fails depending on the preserveParens option #10578
• ast: Incomplete HTML entity handling for JSXText and JSXAttributeValue #9667
• Span mismatches x 5

[leaysgur]

Great progress while I was away~!
(Sorry if my earlier notes just made things messier. 🙇🏻)

I'll also try to work on the remaining mismatches when I am available.

---

• typescript/tests/cases/conformance/expressions/typeGuards/typeGuardNarrowsPrimitiveIntersection.ts
• typescript/tests/cases/conformance/expressions/typeGuards/typeGuardNarrowsToLiteralTypeUnion.ts
• typescript/tests/cases/compiler/controlFlowInstanceofWithSymbolHasInstance.ts
• typescript/tests/cases/conformance/expressions/binaryOperators/instanceofOperator/instanceofOperatorWithRHSHasSymbolHasInstance.ts
• typescript/tests/cases/conformance/types/stringLiteral/stringLiteralTypesAsTags02.ts
• typescript/tests/cases/compiler/narrowingUnionToUnion.ts

It seems that these rest mismatches are all the same root, which was described in #9705 (comment) 👉🏻 #10711

[leaysgur]

Now #10711 and #10739 are merged, #9667 is the last mismatch...! 🎉

[overlookmotel]

Amazing! It's required a herculean effort by many people to get us this far.

I'll tackle field order in next few days, and convert the conformance tester to compare ASTs JSON-to-JSON, which I'm afraid will probably throw up more errors. I suspect in places we're generating JSON like:

{
    "type": "Identifier",
    "name": "foo",
    "optional": false,
    "typeAnnotation": null,
    "optional": true,
    "typeAnnotation": null,
}

But hopefully they won't be too hard to fix.

...and then I'll try to fix #9667.

[leaysgur]

Just a note about field order..., even for the simplest code 1; (just a single Literal), acorn and TS-ESLint seem to have different order.

Does this mean that we need estree(field_order) for JS and TS separately?

[overlookmotel]

My thinking is that both Acorn and TS-ESLint's field orders are pretty arbitrary. TS-ESLint has fields in alphabetical order (but with some random exceptions to that rule!). Acorn's field ordering seems to follow little logic at all.

The field order isn't important per se. What is important is that field order is consistent within our AST for nodes with the same type (i.e. BindingIdentifier and IdentifierReference both create Identifier nodes with fields in same order), because consistent object "shapes" produces better runtime performance for the consumer (and probably makes JSON.parse faster too).

So I now think that my insistence on aligning field order with Acorn was misguided.

I'm planning on taking a different approach now: Order fields in visitation order, based on @typescript-eslint/visitor-keys. I think this will make for a more human-readable AST, and will make it simpler to build a visitor which visits fields in the correct order. I'm working on that now.

So, in short, our field order won't match either Acorn or TS-ESLint. But in my opinion, that's OK!

---

I also intend to move start and end fields (and range / loc once we support them) to be the last in every type.

That's less ideal from a human-readability perspective, but on positive side will allow removing the extra AST traversal to update spans to UTF-16. Updating spans can happen during serialization/raw deserialization pass instead. Removing the extra pass will give us a perf boost.

But that requires the span fields to be last, as the most efficient way to do UTF-8 -> UTF-16 conversion is in ascending order of source position, in which case you can't calculate end until you've visited the node's children. Because JSON is constructed as a text stream, it's difficult to write "end": ??? first, and then later on rewind and replace it with the correct value. It'd get even more tricky once we also support loc.

If anyone thinks this is unacceptable, please speak now!

---

Side note: @leaysgur I see you archived https://github.com/leaysgur/oxc_estree_ts-ast-diff-viewer. Would you mind bringing it back? I used it to help with #10874 after updating to latest TS-ESLint. And field ordering will no doubt throw up more problems, which I'd like to use your excellent tool to help fix!

[ArnaudBarre]

The number of people that look up AST directly from the output is very low so I don't think this is an issue. AST explorer can re-roder fields and put them after type when displayed. As long as you put start before end this would still be better than TS-ESLint 😬

[leaysgur]

So, in short, our field order won't match either Acorn or TS-ESLint. But in my opinion, that's OK!
I also intend to move start and end fields (and range / loc once we support them) to be the last in every type.

I also think both directions make sense.

https://github.com/leaysgur/oxc_estree_ts-ast-diff-viewer

No problem at all! — I’ve restored it.
Since most mismatches had been resolved, I assumed its role was complete. 😅

If you have any requests, feel free to let me know~!

[leaysgur]

I added 2 scripts to leaysgur/oxc_estree_ts-ast-diff-viewer repo. (no view, just scripts)

One is for:

What is important is that field order is consistent within our AST for nodes with the same type (i.e. BindingIdentifier and IdentifierReference both create Identifier nodes with fields in same order),

I have made a PR for this, and no other problems seemed to be found. ✨

---

The other one compares with the order of their visitor-keys.

According to this script, it seems that there are mismatches in the following 32 nodes.

• AccessorProperty
  • theirs: [ "decorators", "key", "typeAnnotation", "value" ]
  • ours: [ "key", "typeAnnotation", "value", "decorators" ]
• ArrayPattern
  • theirs: [ "decorators", "elements", "typeAnnotation" ]
  • ours: [ "elements", "decorators", "typeAnnotation" ]
• ArrowFunctionExpression
  • theirs: [ "typeParameters", "params", "returnType", "body" ]
  • ours: [ "params", "body", "typeParameters", "returnType" ]
• AssignmentPattern
  • theirs: [ "decorators", "left", "right", "typeAnnotation" ]
  • ours: [ "left", "right", "decorators", "typeAnnotation" ]
• CallExpression
  • theirs: [ "callee", "typeArguments", "arguments" ]
  • ours: [ "callee", "arguments", "typeArguments" ]
• ClassDeclaration
  • theirs: [ "decorators", "id", "typeParameters", "superClass", "superTypeArguments", "implements", "body" ]
  • ours: [ "id", "superClass", "body", "decorators", "typeParameters", "superTypeArguments", "implements" ]
• ClassExpression
  • theirs: [ "decorators", "id", "typeParameters", "superClass", "superTypeArguments", "implements", "body" ]
  • ours: [ "id", "superClass", "body", "decorators", "typeParameters", "superTypeArguments", "implements" ]
• ExportSpecifier
  • theirs: [ "exported", "local" ]
  • ours: [ "local", "exported" ]
• FunctionDeclaration
  • theirs: [ "id", "typeParameters", "params", "returnType", "body" ]
  • ours: [ "id", "params", "body", "typeParameters", "returnType" ]
• FunctionExpression
  • theirs: [ "id", "typeParameters", "params", "returnType", "body" ]
  • ours: [ "id", "params", "body", "typeParameters", "returnType" ]
• JSXElement
  • theirs: [ "openingElement", "children", "closingElement" ]
  • ours: [ "openingElement", "closingElement", "children" ]
• JSXFragment
  • theirs: [ "openingFragment", "children", "closingFragment" ]
  • ours: [ "openingFragment", "closingFragment", "children" ]
• JSXOpeningElement
  • theirs: [ "name", "typeArguments", "attributes" ]
  • ours: [ "attributes", "name", "typeArguments" ]
• LabeledStatement
  • theirs: [ "label", "body" ]
  • ours: [ "body", "label" ]
• MethodDefinition
  • theirs: [ "decorators", "key", "value" ]
  • ours: [ "key", "value", "decorators" ]
• NewExpression
  • theirs: [ "callee", "typeArguments", "arguments" ]
  • ours: [ "callee", "arguments", "typeArguments" ]
• ObjectPattern
  • theirs: [ "decorators", "properties", "typeAnnotation" ]
  • ours: [ "properties", "decorators", "typeAnnotation" ]
• PropertyDefinition
  • theirs: [ "decorators", "key", "typeAnnotation", "value" ]
  • ours: [ "key", "value", "decorators", "typeAnnotation" ]
• RestElement
  • theirs: [ "decorators", "argument", "typeAnnotation" ]
  • ours: [ "argument", "decorators", "typeAnnotation" ]
• SwitchCase
  • theirs: [ "test", "consequent" ]
  • ours: [ "consequent", "test" ]
• TaggedTemplateExpression
  • theirs: [ "tag", "typeArguments", "quasi" ]
  • ours: [ "tag", "quasi", "typeArguments" ]
• TemplateLiteral
  • theirs: [ "quasis", "expressions" ]
  • ours: [ "expressions", "quasis" ]
• TSAbstractAccessorProperty
  • theirs: [ "decorators", "key", "typeAnnotation" ]
  • ours: [ "key", "typeAnnotation", "decorators" ]
• TSAbstractPropertyDefinition
  • theirs: [ "decorators", "key", "typeAnnotation" ]
  • ours: [ "key", "decorators", "typeAnnotation" ]
• TSDeclareFunction
  • theirs: [ "id", "typeParameters", "params", "returnType", "body" ]
  • ours: [ "id", "params", "body", "typeParameters", "returnType" ]
• TSEmptyBodyFunctionExpression
  • theirs: [ "id", "typeParameters", "params", "returnType" ]
  • ours: [ "id", "params", "typeParameters", "returnType" ]
• TSImportType
  • theirs: [ "argument", "qualifier", "typeArguments", "options" ]
  • ours: [ "argument", "options", "qualifier", "typeArguments" ]
• TSIndexedAccessType
  • theirs: [ "indexType", "objectType" ]
  • ours: [ "objectType", "indexType" ]
• TSMappedType
  • theirs: [ "key", "constraint", "nameType", "typeAnnotation" ]
  • ours: [ "nameType", "typeAnnotation", "key", "constraint" ]
• TSMethodSignature
  • theirs: [ "typeParameters", "key", "params", "returnType" ]
  • ours: [ "key", "typeParameters", "params", "returnType" ]
• TSPropertySignature
  • theirs: [ "typeAnnotation", "key" ]
  • ours: [ "key", "typeAnnotation" ]
• TSTypePredicate
  • theirs: [ "typeAnnotation", "parameterName" ]
  • ours: [ "parameterName", "typeAnnotation" ]

NOTE:

• They said keys are arranged in the order they appeared in the code, but in some cases this was not the case
• Acorn(jsx) also seems to have a different order 🆚 visitor-keys

[overlookmotel]

• They said keys are arranged in the order they appeared in the code, but in some cases this was not the case

This comment is a really good find.

I have found 6 types where TS-ESLint's visitor keys are not in source code order:

• ExportSpecifier
• TSImportType
• TSIndexedAccessType
• TSMethodSignature
• TSPropertySignature
• TSTypePredicate

I'm going to open an issue on TS-ESLint to fix them, and the fact that they have a comment saying "important: should be sorted in the order that they appear in the source code" will be really helpful in arguing the case.

Unfortunately ExportSpecifier is also in ESTree and Espree has that one in wrong order too, so TS-ESLint won't be able to change that one without diverging from Espree.

I'm still working on making sure there aren't any more cases before I open that issue, though. Am using #10887 to make sure that we have all our fields in the Rust types in source code order first! Currently we have a bug somewhere which I'm still trying to hunt down.

[armano2]

This comment is a really good find.

eslint doesn't really care about order of properties in objects, and instead uses predefined visitor keys

eslint visitor keys can be found in https://github.com/eslint/js/blob/main/packages/eslint-visitor-keys/lib/visitor-keys.js and ts-eslint just extends it with additional values

visitor-keys are used by traverser that is essentially a recursive loop that base on type checks in what order and if fields should be "visitable"

ref:

• traverser: https://github.com/estools/estraverse
• visitor-keys: https://github.com/eslint/js/blob/main/packages/eslint-visitor-keys/lib/visitor-keys.js

---

• They said keys are arranged in the order they appeared in the code, but in some cases this was not the case

this comment refers to visitable fields, and not all fields can/should be visited,
only fields whose child is Node should be visited, eg. loc, range, type is not on this list

---

Note

The iteration order for objects follows a certain set of rules since ES2015, but it does not (always) follow the insertion order.