├── .github
    └── workflows
    │   ├── bb.yml
    │   └── main.yml
├── .gitignore
├── .npmrc
├── logo.svg
├── package.json
└── readme.md


/.github/workflows/bb.yml:
--------------------------------------------------------------------------------
 1 | jobs:
 2 |   main:
 3 |     runs-on: ubuntu-latest
 4 |     steps:
 5 |       - uses: unifiedjs/beep-boop-beta@main
 6 |         with:
 7 |           repo-token: ${{secrets.GITHUB_TOKEN}}
 8 | name: bb
 9 | on:
10 |   issues:
11 |     types: [closed, edited, labeled, opened, reopened, unlabeled]
12 |   pull_request_target:
13 |     types: [closed, edited, labeled, opened, reopened, unlabeled]
14 | 


--------------------------------------------------------------------------------
/.github/workflows/main.yml:
--------------------------------------------------------------------------------
 1 | jobs:
 2 |   main:
 3 |     runs-on: ubuntu-latest
 4 |     steps:
 5 |       - uses: actions/checkout@v4
 6 |       - uses: actions/setup-node@v4
 7 |         with:
 8 |           node-version: node
 9 |       - run: npm install
10 |       - run: npm test
11 | name: main
12 | on:
13 |   - pull_request
14 |   - push
15 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | *.log
3 | node_modules/
4 | 


--------------------------------------------------------------------------------
/.npmrc:
--------------------------------------------------------------------------------
1 | ignore-scripts=true
2 | package-lock=false
3 | 


--------------------------------------------------------------------------------
/logo.svg:
--------------------------------------------------------------------------------
 1 | <svg height="300" viewBox="0 0 1012 300" width="1012" xmlns="http://www.w3.org/2000/svg">
 2 |   <style>
 3 |     .b {fill: #0d1117}
 4 |     .l {fill: #fff}
 5 |     @media (prefers-color-scheme: light) {
 6 |       .b {fill: #fff}
 7 |       .l {fill: #0d1117}
 8 |     }
 9 |   </style>
10 |   <rect class="b" height="300" width="1012" x="0" y="0" />
11 |   <path d="M432.42 140.92L432.42 140.92Q436.61 140.92 438.97 143.77Q441.33 146.63 441.33 151.67L441.33 151.67L423.28 151.67Q423.28 146.60 425.71 143.76Q428.14 140.92 432.42 140.92ZM445.08 161.81L441.27 161.81Q440.54 164.12 438.31 165.41Q436.08 166.70 432.86 166.70L432.86 166.70Q428.47 166.70 425.87 163.78Q423.28 160.87 423.28 155.92L423.28 155.92L423.28 154.83L445.22 154.83L445.22 152.34Q445.22 147.63 443.71 144.32Q442.21 141.01 439.35 139.26Q436.49 137.52 432.42 137.52L432.42 137.52Q428.52 137.52 425.59 139.23Q422.67 140.95 421.05 144.04Q419.44 147.13 419.44 151.29L419.44 151.29L419.44 155.89Q419.44 162.63 422.97 166.38Q426.50 170.13 432.86 170.13L432.86 170.13Q436.05 170.13 438.62 169.10Q441.18 168.08 442.87 166.20Q444.55 164.33 445.08 161.81L445.08 161.81ZM458.17 146.25L458.17 146.25Q458.17 152.67 466.55 154.63L466.55 154.63L471.21 155.74Q474.43 156.50 475.81 157.75Q477.19 158.99 477.19 161.16L477.19 161.16Q477.19 163.74 475.09 165.29Q473.00 166.85 469.45 166.85L469.45 166.85Q466.17 166.85 463.99 165.48Q461.81 164.12 461.19 161.69L461.19 161.69L457.21 161.69Q457.65 165.59 460.90 167.86Q464.15 170.13 469.28 170.13L469.28 170.13Q474.67 170.13 477.92 167.61Q481.17 165.09 481.17 160.93L481.17 160.93Q481.17 157.59 479.03 155.52Q476.89 153.46 472.35 152.37L472.35 152.37L468.08 151.38Q464.85 150.62 463.45 149.38Q462.04 148.15 462.04 146.10L462.04 146.10Q462.04 143.64 464.00 142.18Q465.97 140.71 469.25 140.71L469.25 140.71Q472.26 140.71 474.29 142.05Q476.31 143.38 476.81 145.69L476.81 145.69L480.58 145.69Q480.09 141.94 477.04 139.73Q473.99 137.52 469.36 137.52L469.36 137.52Q464.38 137.52 461.28 139.94Q458.17 142.35 458.17 146.25Z" fill="#03d8d8" />
12 |   <path class="l" d="M503.50 170.16L503.50 170.16Q507.07 170.16 509.60 168.74Q512.14 167.31 513.25 164.65L513.25 164.65L513.66 164.65L513.66 169.63L517.35 169.63L517.35 147.95Q517.35 143.14 514.38 140.46Q511.41 137.78 506.04 137.78L506.04 137.78Q503.00 137.78 500.52 138.82Q498.05 139.86 496.48 141.68Q494.91 143.50 494.62 145.87L494.62 145.87L498.43 145.87Q499.10 143.58 501.08 142.35Q503.06 141.12 506.04 141.12L506.04 141.12Q509.68 141.12 511.58 142.92Q513.49 144.73 513.49 148.13L513.49 148.13L513.49 151.11L504.34 151.52Q499.13 151.76 496.27 154.15Q493.42 156.53 493.42 160.69L493.42 160.69Q493.42 164.97 496.19 167.56Q498.95 170.16 503.50 170.16ZM504.43 166.76L504.43 166.76Q501.15 166.76 499.26 165.13Q497.37 163.51 497.37 160.69L497.37 160.69Q497.37 155.01 504.61 154.69L504.61 154.69L513.49 154.31L513.49 158.70Q513.49 160.96 512.28 162.79Q511.08 164.62 509.03 165.69Q506.98 166.76 504.43 166.76ZM532.35 146.25L532.35 146.25Q532.35 152.67 540.73 154.63L540.73 154.63L545.39 155.74Q548.61 156.50 549.99 157.75Q551.37 158.99 551.37 161.16L551.37 161.16Q551.37 163.74 549.27 165.29Q547.18 166.85 543.63 166.85L543.63 166.85Q540.35 166.85 538.17 165.48Q535.99 164.12 535.37 161.69L535.37 161.69L531.39 161.69Q531.83 165.59 535.08 167.86Q538.33 170.13 543.46 170.13L543.46 170.13Q548.85 170.13 552.10 167.61Q555.35 165.09 555.35 160.93L555.35 160.93Q555.35 157.59 553.21 155.52Q551.07 153.46 546.53 152.37L546.53 152.37L542.25 151.38Q539.03 150.62 537.63 149.38Q536.22 148.15 536.22 146.10L536.22 146.10Q536.22 143.64 538.18 142.18Q540.15 140.71 543.43 140.71L543.43 140.71Q546.44 140.71 548.47 142.05Q550.49 143.38 550.99 145.69L550.99 145.69L554.76 145.69Q554.27 141.94 551.22 139.73Q548.17 137.52 543.54 137.52L543.54 137.52Q538.56 137.52 535.46 139.94Q532.35 142.35 532.35 146.25ZM579.34 129.84L575.51 129.84L575.51 138.05L567.01 138.05L567.01 141.30L575.51 141.30L575.51 160.49Q575.51 163.59 576.77 165.66Q578.03 167.72 580.55 168.75Q583.07 169.78 586.84 169.78L586.84 169.78Q588.22 169.78 590.04 169.66Q591.85 169.54 592.56 169.42L592.56 169.42L592.56 166.14Q591.80 166.26 590.24 166.32Q588.69 166.38 587.05 166.38L587.05 166.38Q583.30 166.38 581.32 164.84Q579.34 163.30 579.34 160.37L579.34 160.37L579.34 141.30L592.56 141.30L592.56 138.05L579.34 138.05L579.34 129.84Z" />
13 | </svg>
14 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "author": "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)",
 3 |   "bugs": "https://github.com/syntax-tree/esast/issues",
 4 |   "contributors": [
 5 |     "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)"
 6 |   ],
 7 |   "description": "ecmascript abstract syntax tree",
 8 |   "devDependencies": {
 9 |     "remark-cli": "^12.0.0",
10 |     "remark-preset-wooorm": "^10.0.0"
11 |   },
12 |   "keywords": [],
13 |   "license": "MIT",
14 |   "private": true,
15 |   "remarkConfig": {
16 |     "plugins": [
17 |       "preset-wooorm"
18 |     ]
19 |   },
20 |   "repository": "syntax-tree/esast",
21 |   "scripts": {
22 |     "format": "remark --frail --output --quiet -- .",
23 |     "test": "npm run format"
24 |   },
25 |   "version": "1.0.0"
26 | }
27 | 


--------------------------------------------------------------------------------
/readme.md:
--------------------------------------------------------------------------------
  1 | <!--lint disable no-html-->
  2 | 
  3 | # [![esast][logo]][site]
  4 | 
  5 | **E**CMA**S**cript **A**bstract **S**yntax **T**ree format.
  6 | 
  7 | ***
  8 | 
  9 | **esast** is a specification for representing [JavaScript][] as an abstract
 10 | [syntax tree][syntax-tree].
 11 | It implements the **[unist][]** spec.
 12 | 
 13 | This document may not be released.
 14 | See [releases][] for released documents.
 15 | The latest released version is [`1.0.0`][latest].
 16 | 
 17 | ## Contents
 18 | 
 19 | * [Introduction](#introduction)
 20 |   * [Where this specification fits](#where-this-specification-fits)
 21 |   * [ESTree](#estree)
 22 | * [Nodes](#nodes)
 23 |   * [`Node`](#node)
 24 |   * [`RegExpLiteral`](#regexpliteral)
 25 |   * [`BigIntLiteral`](#bigintliteral)
 26 | * [Recommendations](#recommendations)
 27 | * [Glossary](#glossary)
 28 | * [List of utilities](#list-of-utilities)
 29 | * [References](#references)
 30 | * [Security](#security)
 31 | * [Related](#related)
 32 | * [Contribute](#contribute)
 33 | * [Acknowledgments](#acknowledgments)
 34 | * [License](#license)
 35 | 
 36 | ## Introduction
 37 | 
 38 | This document defines a format for representing ECMAScript as an [abstract
 39 | syntax tree][syntax-tree].
 40 | Development of esast started in February 2021.
 41 | This specification is written in a [Web IDL][webidl]-like grammar.
 42 | 
 43 | ### Where this specification fits
 44 | 
 45 | esast extends [unist][],
 46 | a format for syntax trees,
 47 | to benefit from its [ecosystem of utilities][utilities].
 48 | There is one important difference with other implementations of unist: children
 49 | are added at fields other than the `children` array and the `children` field is
 50 | not used.
 51 | 
 52 | esast relates to [ESTree][] in that the first is a superset of the latter.
 53 | Any tool that accepts an ESTree also supports esast.
 54 | 
 55 | esast relates to [JavaScript][],
 56 | other than that it represents it,
 57 | in that it has an [ecosystem of utilities][list-of-utilities] for working with
 58 | compliantsyntax trees in JavaScript.
 59 | However,
 60 | esast is not limited to JavaScript and can be used in other programming
 61 | languages.
 62 | 
 63 | esast relates to the [unified][] project in that esast syntax trees are used
 64 | throughout its ecosystem.
 65 | 
 66 | ### ESTree
 67 | 
 68 | ESTree is great but it is missing some things:
 69 | 
 70 | * trees can’t be roundtripped through `JSON.parse(JSON.stringify(s))`,
 71 |   leading to cache troubles
 72 | * columns are 0-indexed,
 73 |   whereas most text editors display 1-indexed columns,
 74 |   leading to a tiny discrepancy or some math to display warnings
 75 | * there is no recommendation for range-based positional info,
 76 |   leading implementations to scatter them in different places
 77 | * there is no safe space for metadata,
 78 |   leading implementations to scatter them in different places
 79 | * there are no recommendations for how to handle JSX,
 80 |   comments,
 81 |   or raw values
 82 | 
 83 | These are minor nits,
 84 | which is why esast is a superset.
 85 | 
 86 | ## Nodes
 87 | 
 88 | ### `Node`
 89 | 
 90 | ```idl
 91 | extend interface Node <: UnistNode {}
 92 | ```
 93 | 
 94 | All esast nodes inherit from unist’s [Node][unist-node] and are otherwise the
 95 | same as their ESTree counterparts,
 96 | with the exception of `RegExpLiteral` and `BigIntLiteral`.
 97 | 
 98 | ### `RegExpLiteral`
 99 | 
100 | The `regex` field on
101 | [`RegExpLiteral`](https://github.com/estree/estree/blob/master/es5.md#regexpliteral)
102 | must be used whereas the `value` field of such literals should be `null` and
103 | must be ignored.
104 | 
105 | ### `BigIntLiteral`
106 | 
107 | The `bigint` field on
108 | [`BigIntLiteral`](https://github.com/estree/estree/blob/master/es2020.md#bigintliteral)
109 | must be used whereas the `value` field of such literals should be `null` and
110 | must be ignored.
111 | 
112 | ## Recommendations
113 | 
114 | For JSX,
115 | follow the
116 | [JSX extension](https://github.com/facebook/jsx/blob/master/AST.md)
117 | maintained in `facebook/jsx`.
118 | 
119 | For type annotations,
120 | follow the
121 | [Type annotations extension](https://github.com/estree/estree/blob/master/extensions/type-annotations.md)
122 | maintained in `estree/estree`.
123 | 
124 | `raw` fields (added by most parsers) should not be used: they create an extra
125 | source of truth,
126 | which is often not maintained.
127 | 
128 | `start`,
129 | `end`,
130 | and `range` fields should not be used.
131 | 
132 | `comments` should not be added on nodes other that `Program`.
133 | When adding comments,
134 | use the `'Block'` (for `/**/`) or `'Line'` (for `//`) types.
135 | Do not use `leading` or `trailing` fields on comment nodes.
136 | 
137 | `tokens` should not be used.
138 | 
139 | ## Glossary
140 | 
141 | See the [unist glossary][glossary] but note of the following deviating terms.
142 | 
143 | ###### Child
144 | 
145 | Node X is **child** of node Y,
146 | if X is either referenced directly or referenced in an array at a field on
147 | node Y.
148 | 
149 | ###### Sibling
150 | 
151 | Node X is a **sibling** of node Y,
152 | if X and Y have the same parent (if any) and X and Y are both referenced in an
153 | array at a field on node Y.
154 | 
155 | ## List of utilities
156 | 
157 | See the [unist list of utilities][utilities] for more utilities.
158 | 
159 | * [`estree-util-attach-comments`](https://github.com/syntax-tree/estree-util-attach-comments)
160 |   — attach comments to estree nodes
161 | * [`estree-util-build-jsx`](https://github.com/syntax-tree/estree-util-build-jsx)
162 |   — transform JSX to function calls
163 | * [`estree-util-is-identifier-name`](https://github.com/syntax-tree/estree-util-is-identifier-name)
164 |   — check if something can be an identifier name
165 | * [`estree-util-value-to-estree`](https://github.com/remcohaszing/estree-util-value-to-estree)
166 |   — convert a JavaScript value to an estree expression
167 | * [`estree-util-to-js`](https://github.com/syntax-tree/estree-util-to-js)
168 |   — serialize as JavaScript
169 | * [`estree-util-visit`](https://github.com/syntax-tree/estree-util-visit)
170 |   — visit nodes
171 | * [`esast-util-from-estree`](https://github.com/syntax-tree/esast-util-from-estree)
172 |   — transform from estree
173 | * [`esast-util-from-js`](https://github.com/syntax-tree/esast-util-from-js)
174 |   — parse from JavaScript
175 | 
176 | Please use either `estree-util-` (if it works with all ESTrees,
177 | preferred)
178 | or `esast-util-` (if it uses on esast specific features) as a prefix.
179 | 
180 | See also the [`estree`](https://github.com/search?q=topic%3Aestree\&s=stars\&o=desc)
181 | topic on GitHub.
182 | 
183 | ## References
184 | 
185 | * **unist**:
186 |   [Universal Syntax Tree][unist].
187 |   T. Wormer; et al.
188 | * **JavaScript**:
189 |   [ECMAScript Language Specification][javascript].
190 |   Ecma International.
191 | * **JSON**
192 |   [The JavaScript Object Notation (JSON) Data Interchange Format][json],
193 |   T. Bray.
194 |   IETF.
195 | * **Web IDL**:
196 |   [Web IDL][webidl],
197 |   C. McCormack.
198 |   W3C.
199 | 
200 | ## Security
201 | 
202 | As esast represents JS,
203 | and JS can open you up to a bunch of problems,
204 | esast is also unsafe.
205 | Always be careful with user input.
206 | 
207 | ## Related
208 | 
209 | * [hast](https://github.com/syntax-tree/hast) — HTML
210 | * [mdast](https://github.com/syntax-tree/mdast) — Markdown
211 | * [nlcst](https://github.com/syntax-tree/nlcst) — Natural language
212 | * [xast](https://github.com/syntax-tree/xast) — XML
213 | 
214 | ## Contribute
215 | 
216 | See [`contributing.md`][contributing] in [`syntax-tree/.github`][health] for
217 | ways to get started.
218 | See [`support.md`][support] for ways to get help.
219 | Ideas for new utilities and tools can be posted in [`syntax-tree/ideas`][ideas].
220 | 
221 | A curated list of awesome `syntax-tree`,
222 | unist,
223 | mdast,
224 | esast,
225 | xast,
226 | and nlcst resources can be found in [awesome syntax-tree][awesome].
227 | 
228 | This project has a [code of conduct][coc].
229 | By interacting with this repository,
230 | organization,
231 | or community you agree to abide by its terms.
232 | 
233 | ## Acknowledgments
234 | 
235 | The initial release of this project was authored by
236 | **[@wooorm](https://github.com/wooorm)**.
237 | 
238 | ## License
239 | 
240 | [CC-BY-4.0][license] © [Titus Wormer][author]
241 | 
242 | <!-- Definitions -->
243 | 
244 | [health]: https://github.com/syntax-tree/.github
245 | 
246 | [contributing]: https://github.com/syntax-tree/.github/blob/HEAD/contributing.md
247 | 
248 | [support]: https://github.com/syntax-tree/.github/blob/HEAD/support.md
249 | 
250 | [coc]: https://github.com/syntax-tree/.github/blob/HEAD/code-of-conduct.md
251 | 
252 | [awesome]: https://github.com/syntax-tree/awesome-syntax-tree
253 | 
254 | [ideas]: https://github.com/syntax-tree/ideas
255 | 
256 | [license]: https://creativecommons.org/licenses/by/4.0/
257 | 
258 | [author]: https://wooorm.com
259 | 
260 | [logo]: https://raw.githubusercontent.com/syntax-tree/esast/0164416/logo.svg?sanitize=true
261 | 
262 | [site]: https://unifiedjs.com
263 | 
264 | [releases]: https://github.com/syntax-tree/esast/releases
265 | 
266 | [latest]: https://github.com/syntax-tree/esast/releases/tag/2.3.0
267 | 
268 | [list-of-utilities]: #list-of-utilities
269 | 
270 | [unist]: https://github.com/syntax-tree/unist
271 | 
272 | [syntax-tree]: https://github.com/syntax-tree/unist#syntax-tree
273 | 
274 | [javascript]: https://www.ecma-international.org/ecma-262/9.0/index.html
275 | 
276 | [json]: https://tools.ietf.org/html/rfc7159
277 | 
278 | [webidl]: https://heycam.github.io/webidl/
279 | 
280 | [glossary]: https://github.com/syntax-tree/unist#glossary
281 | 
282 | [utilities]: https://github.com/syntax-tree/unist#list-of-utilities
283 | 
284 | [unified]: https://github.com/unifiedjs/unified
285 | 
286 | [estree]: https://github.com/estree/estree
287 | 
288 | [unist-node]: https://github.com/syntax-tree/unist#node
289 | 


--------------------------------------------------------------------------------