Skip to content

Commit e027d74

Browse files
author
Erlend Oftedal
committed
Update README
1 parent 766c3e1 commit e027d74

1 file changed

Lines changed: 83 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 83 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,69 @@
1-
# astronomical-viewer
1+
# 🌌 Astronomical Query Viewer
22

3-
This template should help get you started developing with Vue 3 in Vite.
3+
An interactive JavaScript AST (Abstract Syntax Tree) explorer and query tool, similar to [Regexr](https://regexr.com/) but for the [Astronomical](https://github.com/RetireJS/astronomical) query language.
44

5-
## Recommended IDE Setup
5+
**🚀 [Try it live](https://erlend.github.io/astronomical-viewer/)**
66

7-
[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
7+
## What is this?
88

9-
## Recommended Browser Setup
9+
Astronomical Query Viewer helps you visualize and test [Astronomical](https://github.com/RetireJS/astronomical) queries against JavaScript code. It provides:
1010

11-
- Chromium-based browsers (Chrome, Edge, Brave, etc.):
12-
- [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
13-
- [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters)
14-
- Firefox:
15-
- [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
16-
- [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/)
11+
- **Interactive AST Tree View** - See the complete Abstract Syntax Tree of your JavaScript code
12+
- **Query Testing** - Write and test Astronomical queries in real-time
13+
- **Visual Feedback** - Matched nodes are highlighted with their ancestors marked for easy navigation
14+
- **Persistent State** - Your code and queries are saved in localStorage
1715

18-
## Type Support for `.vue` Imports in TS
16+
## Features
1917

20-
TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
18+
- 📝 **Dual Pane Editor** - JavaScript code on one side, Astronomical queries on the other
19+
- 🌳 **Full AST Visualization** - Explore the entire syntax tree with expand/collapse functionality
20+
- 🎯 **Match Highlighting** - Matched nodes shown in yellow, ancestors in gray
21+
- 💾 **Auto-Save** - Your work persists across browser sessions
22+
- 🔍 **Primitive Results** - Shows both matched AST nodes and primitive values (strings, numbers, booleans)
23+
- ⚡ **Real-time Updates** - Execute queries and see results instantly
2124

22-
## Customize configuration
25+
## What is Astronomical?
2326

24-
See [Vite Configuration Reference](https://vite.dev/config/).
27+
[Astronomical](https://github.com/RetireJS/astronomical) is a query language for JavaScript ASTs, similar to XPath for XML. It allows you to search for specific patterns in JavaScript code using queries like:
2528

26-
## Project Setup
29+
```
30+
//FunctionDeclaration/:id/:name # Get all function names
31+
//Identifier[/:name == "exports"] # Find all "exports" identifiers
32+
//CallExpression[/Identifier/:name == "require"] # Find all require() calls
33+
```
34+
35+
## Usage
36+
37+
1. **Paste JavaScript code** into the top textarea
38+
2. **Write an Astronomical query** in the query field (supports multiline)
39+
3. **Click "Execute Query"** to see matches
40+
4. **Explore the AST** - Click nodes to expand/collapse the tree
41+
42+
### Example Queries
43+
44+
Find all function declarations:
45+
46+
```
47+
//FunctionDeclaration
48+
```
49+
50+
Get all function names:
51+
52+
```
53+
//FunctionDeclaration/:id/:name
54+
```
55+
56+
Find all variable declarations with specific names:
57+
58+
Find all variable declarations with specific names:
59+
60+
```
61+
//VariableDeclarator[/:id/:name == "exports"]
62+
```
63+
64+
## Development
65+
66+
### Project Setup
2767

2868
```sh
2969
npm install
@@ -46,3 +86,30 @@ npm run build
4686
```sh
4787
npm run lint
4888
```
89+
90+
## Technology Stack
91+
92+
- **Vue 3** - Progressive JavaScript framework
93+
- **TypeScript** - Type safety and better developer experience
94+
- **Vite** - Fast build tool and dev server
95+
- **Astronomical** - JavaScript AST query engine
96+
- **Meriyah** - Fast ECMAScript parser (used by Astronomical)
97+
98+
## Known Limitations
99+
100+
- Astronomical's `/:$object` binding feature may fail for runtime-provided identifiers (like `exports`, `module`, `require` in CommonJS) that aren't explicitly declared in the source code
101+
- The viewer shows the static AST structure and doesn't have access to runtime context
102+
103+
## Contributing
104+
105+
Contributions are welcome! Please feel free to submit issues or pull requests.
106+
107+
## License
108+
109+
This project is open source. See LICENSE file for details.
110+
111+
## Related Projects
112+
113+
- [Astronomical](https://github.com/RetireJS/astronomical) - The query engine powering this viewer
114+
- [AST Explorer](https://astexplorer.net/) - General purpose AST visualization tool
115+
- [Regexr](https://regexr.com/) - Similar interactive tool for regular expressions

0 commit comments

Comments
 (0)