Crate amql_engine

Source

Expand description

AQL engine: parse, index, query, and validate code annotations.

All domain logic lives here. Surface crates (CLI, MCP server, WASM) are thin shims that call into this crate.

Modules§

meta: Project identity constants and accessors — single source of truth for all crates.

Structs§

Annotation: A single annotation entry from an .aqm file.
AnnotationStore: In-memory index of annotation sidecar files.
AnnotationSummary: Summary of an annotation attached to a code element.
AqlError: Error type for AQL operations.
AqlSymbol: A symbol extracted from an .aqm file for editor outline/navigation.
AttrDefinition: Definition of a tag attribute.
AttrName: Attribute key in metadata maps.
AttrSummary: Statistical summary of an attribute across annotation instances.
BatchMutationResult: Result of a batch mutation across multiple files.
BenchCase: A single benchmark scenario comparing multiple baselines against AQL.
BenchConfig: Parsed benchmark configuration from .config/aql.bench.
BenchRequest: Input for a single bench run. Shims construct this from their input format.
BenchResponse: Output from a bench run.
BenchResult: Result of running a single benchmark case.
Binding: Annotation-to-code join key.
CodeCache: Per-file cache of parsed CodeElement trees with mtime invalidation.
CodeElement: A node in the universal code element tree.
CodeElementName: Name of a code construct.
CodeElementSummary: Summary of a matched code element.
ColocatedLocator: Default strategy: sidecar lives next to its source file with .aqm extension. src/api.ts → src/api.aqm
CompoundSelector: A single compound selector: optional tag + zero or more attribute predicates.
CompressionResult: Compression measurement result from in-memory data.
DeclareAttr: Attribute definition within a DeclareTag.
DeclareConfig: User-facing config for declare(). All fields have sensible defaults.
DeclareExtractor: Extractor definition within a DeclareConfig.
DeclareTag: Tag definition within a DeclareConfig.
Delta: What is unique about a specific annotation relative to the pattern.
DetectedStacks: Result of stack detection.
DiffChange: An annotation that changed between baseline and current.
DiffEntry: A single annotation in a diff.
DiffResult: Summary of annotation changes between two states.
DirectoryLocator: Centralized strategy: all sidecars live under a single directory, mirroring the source tree structure. With base = ".annotations": src/api.ts → .annotations/src/api.aqm
ExpressExtractor: Built-in Express route/middleware extractor.
ExtractorConfig: Configuration for a single extractor, parsed from the manifest.
ExtractorRegistry: Registry of built-in extractors indexed by name.
ExtractorResult: Result of running a single extractor.
FileCompression: Per-file compression detail.
FileCoverage: Per-file annotation coverage entry.
FileDiffCoverage: Per-file coverage for a specific set of files (diff-aware).
FileEntry: Input format for loading annotations: a file path and its XML content.
FileSummary: Detailed single-file annotation summary.
GoHttpExtractor: Built-in Go HTTP route/middleware extractor.
GoResolver: Go source file resolver using tree-sitter.
GoStructureExtractor: General-purpose Go structure extractor.
GoTestExtractor: Built-in Go test/benchmark extractor.
Manifest: A parsed AQL manifest from .config/aql.schema.
MeasuredOutput: Measured output from one approach.
MutationRequest: A single mutation to apply to a source file node.
MutationResult: Result of a mutation operation.
NavResult: Result of a navigation operation that returns nodes.
NodeKind: tree-sitter AST node kind identifier.
NodeRef: A self-contained reference to a node in a source file.
Pattern: Common structure across all annotations of a tag.
PatternResult: Result of pattern extraction: the common pattern and per-instance deltas.
Predicate: A predicate expression: name, name=value, name^=value, etc.
ProjectRoot: Absolute path to the project root directory.
ProjectStats: Aggregate project statistics for token burn reporting.
QueryContext: Context passed to each middleware.
QueryOptions: Options applied to query and select result sets after matching.
QueryPipeline: Builder and runner for AQL queries.
QueryPipelineBuilder: Builder for QueryPipeline.
QueryResult: Enriched query result.
ReactExtractor: Built-in React component/hook extractor.
RelativePath: Source file path relative to project root.
RepairSuggestion: A suggested fix for a broken annotation binding.
ResolverRegistry: Registry of Code Resolvers by file extension. Uses an FxHashMap for O(1) extension lookup instead of linear scan.
RustResolver: Rust source file resolver using tree-sitter.
RustStructureExtractor: General-purpose Rust structure extractor.
Scope: Query scope prefix (directory, file, or empty).
SelectorAst: Parsed selector AST — a chain of compound selectors.
SelectorStr: Raw selector string before parsing.
SidecarEdit: A text edit to apply to an .aqm sidecar file.
SourceEntry: A source file entry for in-memory benchmarking.
SourceLocation: Location of a code element in a source file.
SpotCheckFailure: A single binding that failed the spot check.
SpotCheckResult: Result of spot-checking annotation bindings against code elements.
TagDefinition: Definition of an annotation tag.
TagName: Annotation or code element tag name.
TestExtractor: Built-in test framework extractor.
TransactionResult: Result of a successfully committed transaction.
TypeScriptResolver: TypeScript/JavaScript source file resolver using tree-sitter.
TypeScriptStructureExtractor: General-purpose TypeScript/JavaScript structure extractor.
ValidationResult: A validation result.

Enums§

AqlDef: AQL approach definition.
AttrType: Attribute type enumeration.
BaselineDef: Baseline approach definition.
Combinator: Combinator between compound selectors.
InsertPosition: Position relative to a target node for insertion.
MutationOp: Mutation operation to perform on a node.
PredicateOp: Comparison operator.
PredicateValue: Typed predicate value.
Stack: Detected project stack.
TransactionCondition: A condition evaluated against the in-memory buffer during a transaction.
TransactionOp: A single operation within a transaction.
ValidationLevel: Severity level.

Constants§

BUILTIN_ATTRS: Built-in attributes available on all tags without manifest definition.
CLI_ONLY: Operations exposed only by amql-cli (no MCP equivalent required). mcp is a transport command that starts the MCP server itself.
MCP_ONLY: Operations exposed only by amql-mcp-server (no CLI equivalent required). Entries here must NOT appear in SURFACE.
NON_GENERATED_BUILTINS: Built-in attributes that are never generated (human/agent-authored only).
SCHEMA_VERSION: Current AQL schema version.
SOURCE_EXTENSIONS: Source extensions the engine’s resolver registry handles.
SURFACE: Operations that MUST be exposed by both amql-cli (as a Command variant) and amql-mcp-server (as an aql_{op} tool function). Names are lowercase snake_case.

Traits§

BuiltinExtractor: A built-in extractor that discovers annotations from source code.
CodeResolver: A Code Resolver resolves source files into universal CodeElement trees.
Matchable: A matchable node — works for both annotations and code elements.
QueryMiddleware: A middleware that can transform query results after AQL runs them.
SidecarLocator: Strategy for locating .aqm sidecar files relative to source files.

Functions§

apply_edits: Apply edits to XML content. Edits must be sorted descending by start_byte.
auto_detect_cases: Auto-generate benchmark cases by scanning the project.
batch_mutate: Execute multiple mutations in parallel across files.
batch_query: Run multiple selectors in parallel against the same scope.
count_source_files: Count source files in a project.
declare_config: Validate a DeclareConfig and produce a Manifest.
detect_stacks: Detect project stacks from marker files in the given directory.
diff_annotations: Compute the diff between baseline annotations and current annotations.
diff_file_coverage: Annotation coverage for a specific set of files (diff-aware).
diff_from_pattern: Given a pattern and a specific annotation, return only what is unique.
execute_bench_request: Execute a bench request end-to-end: validate, build cases, run, return results.
execute_transaction: Execute a declarative transaction: apply ops to an in-memory buffer, then flush to disk only if all ops succeed. On error nothing is written.
expand: Return the parent node, or the nearest ancestor matching an optional selector.
expand_node: Expand: return parent or nearest ancestor matching selector.
extract_aql_symbols: Extract symbols from .aqm document text for editor features (outline, go-to).
extract_bind_from_line: Extract the bind="..." value from a single line of AQL XML.
extract_pattern: Analyze all annotations of a tag and return the common pattern.
file_coverage: Per-file annotation coverage report.
file_summary: Detailed single-file annotation summary.
filter_by_selector: Filter an array of flat nodes by a selector AST. Returns indices into the input slice for matched nodes.
filter_by_selector_indexed: Filter nodes using parent indices for combinator matching. parent_indices[i] is the index of node i’s parent in nodes, or None.
find_project_root: Walk up from start_dir looking for .config/aql.schema. Returns the project root directory (parent of .config/), or None.
format_bench_table
generate_schema: Generate a .config/aql.schema XML string for the detected stacks.
glob_annotation_files: Backward-compatible alias for glob_aql_files.
glob_aql_files: Glob for .aqm files in a project, using the ignore crate for .gitignore-aware walking. Uses parallel walking for performance.
glob_source_files: Glob source files within a scope, filtered to resolver-supported extensions. Reuses ignore::WalkBuilder pattern from glob_annotation_files.
init_project: Run aql init: detect stacks and write .config/aql.schema.
insert: Insert source text relative to a target node. Writes back to disk.
insert_source: Insert source text relative to a target node.
json_value_to_string: Shared utility: convert a JSON value to a string representation. Returns Cow::Borrowed for the String variant to avoid allocation.
load_manifest: Load and parse a manifest from project_root/.config/aql.schema.
matches_compound: Test if a single node matches a compound selector (tag + attributes).
measure_compression: Measure compression from pre-loaded source files and annotations.
move_node: Move a node to a new position relative to a target. Both must be in the same file. Writes back to disk.
move_node_in_source: Move a node to a new position relative to a target. Both nodes must be in the same file (same source text).
nav_select: Select nodes matching a structural selector within a scope.
next: Return the next named sibling, or the next sibling matching a selector.
next_node: Next: return next named sibling matching selector.
parse_bench_config: Parse a benchmark config from a raw XML string.
parse_manifest: Parse a manifest from a raw XML string.
parse_selector: Parse a selector string into an AST.
pattern_with_deltas: Extract the pattern and compute deltas for every instance of a tag.
prev: Return the previous named sibling, or the previous sibling matching a selector.
prev_node: Prev: return previous named sibling matching selector.
project_name: Derive a project name from the project root directory.
project_stats: Compute project statistics from loaded stores.
read_source: Read the source text of a node.
remove: Remove a node from its source file. Returns the modified source and detached text.
remove_node: Remove a node from the source text, returning the modified source and the detached node’s text.
replace: Replace a node’s source text. Writes back to disk.
replace_node: Replace a node’s source text with new content.
resolve_bind_name: Resolve qualified bindings: Foo.bar → bar.
run_all_extractors: Run all extractors defined in the manifest and collect results.
run_bench: Execute all benchmark cases and collect results.
run_extractor: Run a single extractor as a subprocess and parse its JSON output.
select_nodes: Select all named descendants matching a selector within a scope.
shrink: Return the first child matching an optional selector, or all direct children.
shrink_node: Shrink: return children matching selector, or all named children.
sidecar_for_colocated: Derive the colocated sidecar path from a source path. src/api.ts → src/api.aqm
source_candidates: Candidate source paths for a sidecar. Inverse of sidecar_for_colocated.
spot_check_bindings: Spot-check annotation bindings against parsed code elements.
suggest_repairs: Find annotations with bindings that look potentially broken and suggest repairs based on other annotations and code element names. If code_cache is provided, code element names are included in the known names set.
suggest_repairs_from_annotations: Suggest repairs using only annotation data (no code cache).
sync_sidecar: Compute minimal edits to sync an .aqm sidecar with new annotations.
unified_query: Main query entry point.
validate: Validate all loaded annotations against the manifest. Parallelizes per-file validation via rayon when the fs feature is enabled.

Type Aliases§

AttrOp: Alias for PredicateOp (backwards compatibility).
AttrPredicate: Alias for Predicate (backwards compatibility).
FileLockManager: Per-file lock manager keyed by RelativePath.
FxHashMap: Type alias for a hash map that uses the Fx hashing algorithm.

Crate amql_engine

Crate amql_engine Copy item path

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate amql_engine