How jarbear82/hyperql works
1. Repo purpose
- This repository is a language-tooling stack for HyperQL, a graph-relational query language.
- It is not an application backend; it is centered on parsing, editor support, and language-server integration.
2. Source-of-truth language assets
- hyperql-language-specification/ holds versioned JSON specifications for language editions 0-17, 0-18, and 0-19.
- That folder also includes example .hql files and design notes/proposals, which serve as the human-readable reference material for the language.
3. Tree-sitter grammar package
- tree-sitter-hyperql/ is the core parser project.
- It contains the grammar definition (grammar.js) plus generated parser artifacts in src/ such as parser.c, grammar.json, and node-types.json.
- This is the main boundary where language syntax becomes an executable parse tree.
4. Multi-language parser bindings
- The Tree-sitter package exposes bindings for C, Go, Java, Node.js, Python, Rust, and Zig under bindings/.
- These bindings let other tools embed the HyperQL parser without reimplementing the grammar.
- Architecturally, this makes the parser the shared core consumed by editor tooling and any external integrations.
5. Editor extension layer for Zed
- hyperql-zed/ is the Zed editor extension, implemented as a Rust crate.
- It ships a compiled grammar artifact (grammars/hyperql.wasm) and Tree-sitter query files for syntax features: highlights.scm, indents.scm, and outline.scm.
- languages/hyperql/config.toml defines editor-facing language configuration for Zed.
6. Language-server layer
- hyperql-lsp/ is a separate Zig-based Language Server Protocol server.
- The README indicates it provides at least basic diagnostics.
- This layer is the runtime bridge between the language grammar and editor feedback, independent from the Zed extension packaging.
7. Primary runtime/data flow
- HyperQL language definitions and examples inform the grammar in tree-sitter-hyperql/.
- The Tree-sitter parser produces parse trees used by editor queries and by any bindings.
- The Zed extension consumes the parser/queries for syntax highlighting, indentation, and outline extraction.
- The LSP server provides diagnostics back to the editor, likely using the same language rules or parser-derived checks.
8. Build and packaging boundaries
- tree-sitter-hyperql/ is built with the standard Tree-sitter toolchain and supports multiple package managers/build systems (Cargo, npm, pip, Go, Maven, Zig, CMake, Makefile).
- hyperql-lsp/ is built with Zig (build.zig), while hyperql-zed/ is a Rust extension package (Cargo.toml, extension.toml).
- This repo therefore has three distinct packaging targets: parser library, editor extension, and LSP binary.
9. Setup and developer workflow
- setup.sh and setup.ps1 automate local development setup, especially building the LSP and wiring the Zed extension to local paths.
- uninstall.sh and uninstall.ps1 reverse that local installation.
- The README’s build steps show the parser must be built separately before editor integration works.
10. Quality, compliance, and release hygiene
- .github/workflows/license-check.yml, deny.toml, and THIRD_PARTY_LICENSES.md indicate dependency/license governance.
- This matters because the repository distributes generated parser code and bindings across ecosystems, so license compliance is part of the release boundary.
11. What an architecture diagram should show
- Put the Tree-sitter grammar in the center as the shared syntax engine.
- Draw inbound arrows from the language specification/examples into the grammar.
- Draw outbound arrows from the grammar to generated parser artifacts, language bindings, and the Zed extension queries.
- Show the Zig LSP server as a parallel consumer/validator that returns diagnostics to the editor.
- Keep the Zed extension and LSP server separate, since they are packaged and built independently even though both serve editor integration.
Main entry points: grammar.js Grammar · package.json Parser pkg · bindings Bindings · Cargo.toml Zed extension
Components 14
Language Spec
Versioned HyperQL reference material and examples.
- Spec docs · Versioned language specification JSON plus human-readable proposals and review notes.
hyperql-language-specification - Examples · Example .hql and .hyperql files used as reference inputs for language behavior.
hyperql-language-specification/Example_HQL_Files - Proposals · Ideas and proposal documents that shape future language evolution.
hyperql-language-specification/Ideas
Parser Core
Tree-sitter grammar, generated artifacts, and bindings.
- Grammar · Core HyperQL syntax definition that drives parse generation.
tree-sitter-hyperql/grammar.js - Parser C · Generated Tree-sitter parser implementation and core parse tables.
tree-sitter-hyperql/src/parser.c - Node types · Generated grammar metadata consumed by bindings and tooling.
tree-sitter-hyperql/src/grammar.json - Bindings · C, Go, Java, Node.js, Python, Rust, and Zig bindings for embedding the parser.
tree-sitter-hyperql/bindings - Queries · Shared Tree-sitter queries for highlighting, indentation, and outline extraction.
tree-sitter-hyperql/queries - Parser pkg · Tree-sitter package boundary and build metadata for distribution across ecosystems.
tree-sitter-hyperql/package.json
Editor Integration
Zed extension and LSP runtime layers.
- Zed extension · Zed integration package that ships the HyperQL grammar artifact and editor configuration.
hyperql-zed/Cargo.toml - Zed config · Language configuration and Tree-sitter query files used by Zed.
hyperql-zed/languages/hyperql/config.toml - LSP server · Zig-based language server that provides diagnostics and editor feedback.
hyperql-lsp/src/main.zig
Tooling
Setup and release-governance boundaries.
- Setup scripts · Helper scripts for wiring local builds and editor integration.
setup.sh - License checks · Dependency and license compliance boundaries for generated code and packaged artifacts.
deny.toml
Connections 16
- Spec docs → Grammar: defines · Language editions and reference material inform grammar evolution.
- Examples → Grammar: exercises · Example queries provide coverage for syntax behavior.
- Proposals → Grammar: proposes · Design proposals feed future grammar changes.
- Grammar → Parser C: generates · Tree-sitter compiles the grammar into parser artifacts.
- Grammar → Node types: derives · The grammar defines node types and parse structure metadata.
- Grammar → Bindings: shared by · Bindings expose the same parser core to multiple host languages.
- Parser C → Bindings: embedded in · Generated parser code is consumed by the language bindings.
- Parser pkg → Bindings: packages · The parser package boundary distributes bindings and build targets.
- Queries → Zed config: consumed by · Zed uses Tree-sitter queries for highlighting, indentation, and outline.
- Bindings → Zed extension: parses for · The editor extension relies on the parser through generated grammar assets.
- Parser pkg → Zed extension: supplies · The extension package ships the compiled grammar artifact and integration glue.
- Parser pkg → LSP server: supports · The language server depends on parser behavior for validation and diagnostics.
- Zed extension → LSP server: pairs with · The editor extension and language server are separate integration layers.
- Setup scripts → Zed extension: wires · Bootstrap scripts configure local paths for Zed development.
- Setup scripts → LSP server: builds · Bootstrap scripts help compile and install the Zig LSP server.
- License checks → Parser pkg: governs · License checks cover the distributed parser package and generated artifacts.