amql-engine

Core domain logic for AQL: parse, index, query, and validate code annotations

Role

• All domain logic lives here
• Surface crates (CLI, MCP, LSP, WASM) are thin shims into this crate
• No surface crate contains domain logic — D ⊂ amql-engine

Features

• default = ["resolver", "fs"]
• resolver — tree-sitter code resolution (Rust, TypeScript, Go)
• fs — filesystem access (globbing, caching, file I/O)
• wasm — WASM bindings via wasm_bindgen (excludes resolver + fs)
• ts — TypeScript type generation via ts-rs

Key Modules

• store — load, index, query .aqm annotation sidecars
• selector — CSS-like selector parsing and matching
• navigate — tree-sitter AST navigation and source mutation
• sync — incremental sidecar sync (source change → minimal XML edits)
• extractor — built-in framework extractors (Express, React, Go, Rust, tests)
• query — unified annotation + code element queries
• transact — atomic multi-step source mutations with rollback

Getting Started

use aql_engine::{AnnotationStore, Scope};
use std::path::Path;

// Load annotations
let mut store = AnnotationStore::new(Path::new("/project"));
let errors = store.load_all_from_locator();

// Query by selector
let results = store.select("controller[method=\"POST\"]", None, None, None)?;

// Incremental sidecar sync
use aql_engine::{sync_sidecar, apply_edits};
let edits = sync_sidecar(&old_xml, &new_annotations);
let updated_xml = apply_edits(&old_xml, &edits);

npm

• Package: @aql/engine
• Build: bun run build (via turborepo → wasm-pack + codegen)
• All TypeScript types generated from Rust via ts-rs
• All JS wrappers generated from embedded Rust consts

License

MIT