amql_engine/

lib.rs

//! 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.

#[cfg(all(feature = "resolver", feature = "fs"))]
mod bench;
#[cfg(feature = "fs")]
mod code_cache;
mod compression;
#[cfg(all(feature = "resolver", feature = "fs"))]
mod coverage;
mod declare;
mod diff;
mod error;
#[cfg(feature = "fs")]
mod extractor;
mod file_lock;
#[cfg(feature = "fs")]
mod init;
mod manifest;
mod matcher;
pub mod meta;
#[cfg(feature = "resolver")]
mod navigate;
mod paths;
mod pattern;
#[cfg(all(feature = "resolver", feature = "fs"))]
mod pipeline;
#[cfg(all(feature = "resolver", feature = "fs"))]
mod query;
mod query_options;
mod repair;
#[cfg(feature = "resolver")]
mod resolver;
mod selector;
mod sidecar;
#[cfg(all(feature = "resolver", feature = "fs"))]
mod stats;
mod store;
mod sync;
mod transact;
mod types;
mod validator;
#[cfg(feature = "wasm")]
mod index;
mod xml;

#[cfg(all(feature = "resolver", feature = "fs"))]
pub use bench::{
    auto_detect_cases, count_source_files, execute_bench_request, format_bench_table,
    parse_bench_config, project_name, run_bench, AqlDef, BaselineDef, BenchCase, BenchConfig,
    BenchRequest, BenchResponse, BenchResult, MeasuredOutput,
};
#[cfg(feature = "fs")]
pub use code_cache::{glob_source_files, CodeCache};
pub use compression::{measure_compression, CompressionResult, FileCompression, SourceEntry};
#[cfg(all(feature = "resolver", feature = "fs"))]
pub use coverage::{
    diff_file_coverage, file_coverage, file_summary, spot_check_bindings, FileCoverage,
    FileDiffCoverage, FileSummary, SpotCheckFailure, SpotCheckResult,
};
pub use declare::{declare_config, DeclareAttr, DeclareConfig, DeclareExtractor, DeclareTag};
pub use diff::{diff_annotations, DiffChange, DiffEntry, DiffResult};
pub use error::AqlError;
#[cfg(feature = "fs")]
pub use extractor::{run_all_extractors, run_extractor, ExtractorResult};
#[cfg(feature = "fs")]
pub use extractor::{BuiltinExtractor, ExtractorRegistry};
#[cfg(all(feature = "fs", feature = "resolver"))]
pub use extractor::{
    ExpressExtractor, GoHttpExtractor, GoStructureExtractor, GoTestExtractor, ReactExtractor,
    RustStructureExtractor, TestExtractor, TypeScriptStructureExtractor,
};
pub use file_lock::FileLockManager;
#[cfg(feature = "fs")]
pub use init::init_project;
#[cfg(feature = "fs")]
pub use init::{detect_stacks, generate_schema, DetectedStacks, Stack};
pub use manifest::ExtractorConfig;
#[cfg(feature = "fs")]
pub use manifest::{find_project_root, load_manifest};
pub use manifest::{
    parse_manifest, AttrDefinition, AttrType, Manifest, TagDefinition, BUILTIN_ATTRS,
    NON_GENERATED_BUILTINS, SCHEMA_VERSION,
};
pub use matcher::{filter_by_selector, filter_by_selector_indexed, matches_compound, Matchable};
#[cfg(feature = "resolver")]
pub use navigate::{
    batch_mutate,
    expand,
    expand_node,
    insert,
    insert_source,
    move_node,
    move_node_in_source,
    next,
    next_node,
    prev,
    prev_node,
    read_source,
    remove,
    remove_node,
    replace,
    replace_node,
    select as nav_select,
    // Pure functions (no file I/O) — for direct use by consumers
    select_nodes,
    shrink,
    shrink_node,
    BatchMutationResult,
    InsertPosition,
    MutationOp,
    MutationRequest,
    MutationResult,
    NavResult,
    NodeRef,
};
pub use pattern::{
    diff_from_pattern, extract_pattern, pattern_with_deltas, AttrSummary, Delta, Pattern,
    PatternResult,
};
#[cfg(all(feature = "resolver", feature = "fs"))]
pub use pipeline::{QueryContext, QueryMiddleware, QueryPipeline, QueryPipelineBuilder};
#[cfg(all(feature = "resolver", feature = "fs"))]
pub use query::{batch_query, unified_query, AnnotationSummary, CodeElementSummary, QueryResult};
pub use query_options::QueryOptions;
pub use repair::{suggest_repairs, suggest_repairs_from_annotations, RepairSuggestion};
#[cfg(feature = "resolver")]
pub use resolver::{
    CodeElement, CodeResolver, GoResolver, ResolverRegistry, RustResolver, SourceLocation,
    TypeScriptResolver,
};
pub use selector::{
    parse_selector, AttrOp, AttrPredicate, Combinator, CompoundSelector, Predicate, PredicateOp,
    PredicateValue, SelectorAst,
};
pub use sidecar::{
    extract_aql_symbols, extract_bind_from_line, resolve_bind_name, sidecar_for_colocated,
    source_candidates, AqlSymbol, SidecarLocator, SOURCE_EXTENSIONS,
};
#[cfg(feature = "fs")]
pub use sidecar::{ColocatedLocator, DirectoryLocator};
#[cfg(all(feature = "resolver", feature = "fs"))]
pub use stats::{project_stats, ProjectStats};
#[cfg(feature = "fs")]
pub use store::{glob_annotation_files, glob_aql_files};
pub use store::{Annotation, AnnotationStore, FileEntry};
pub use sync::{apply_edits, sync_sidecar, SidecarEdit};
pub use transact::{execute_transaction, TransactionCondition, TransactionOp, TransactionResult};
pub use types::{
    AttrName, Binding, CodeElementName, NodeKind, ProjectRoot, RelativePath, Scope, SelectorStr,
    TagName,
};
pub use validator::{validate, ValidationLevel, ValidationResult};

pub use rustc_hash::FxHashMap;

/// 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.
///
/// Adding an entry here causes both shim surface-coverage tests to fail until the
/// operation is implemented in both shims.
pub const SURFACE: &[&str] = &[
    "bench",
    "diff",
    "extract",
    "init",
    "locate",
    "nav_insert",
    "nav_read",
    "nav_remove",
    "nav_replace",
    "nav_select",
    "query",
    "repair",
    "schema",
    "select",
    "stats",
    "transact",
    "validate",
];

/// Operations exposed only by `amql-cli` (no MCP equivalent required).
/// `mcp` is a transport command that starts the MCP server itself.
pub const CLI_ONLY: &[&str] = &["mcp"];

/// Operations exposed only by `amql-mcp-server` (no CLI equivalent required).
/// Entries here must NOT appear in `SURFACE`.
pub const MCP_ONLY: &[&str] = &[
    "batch_mutate",
    "batch_query",
    "coverage",
    "diff_coverage",
    "file_summary",
    "nav_expand",
    "nav_move",
    "nav_next",
    "nav_prev",
    "nav_shrink",
    "pattern",
    "refresh",
    "spot_check",
];

use serde_json::Value as JsonValue;
use std::borrow::Cow;

/// Shared utility: convert a JSON value to a string representation.
/// Returns `Cow::Borrowed` for the `String` variant to avoid allocation.
pub fn json_value_to_string(v: &JsonValue) -> Cow<'_, str> {
    match v {
        JsonValue::String(s) => Cow::Borrowed(s.as_str()),
        JsonValue::Bool(b) => Cow::Owned(b.to_string()),
        JsonValue::Number(n) => Cow::Owned(n.to_string()),
        JsonValue::Null => Cow::Borrowed(""),
        other => Cow::Owned(other.to_string()),
    }
}

// ---------------------------------------------------------------------------
// TypeScript/Flow codegen — generates wasm.d.ts + wasm.js.flow for the npm package
// ---------------------------------------------------------------------------

#[cfg(all(test, feature = "codegen"))]
mod ts_codegen {
    use wasm_js_bridge::{generate_index_dts, generate_index_flow, OpaqueType, TypeAlias, WasmFn};

    /// Collect both TS and Flow declarations from a single type list.
    /// Each entry is a Rust type path — the macro calls `TS::decl` and `Flow::decl` once each.
    macro_rules! collect_decls {
        ($ts_cfg:expr, $flow_cfg:expr, [ $($ty:ty),* $(,)? ]) => {{
            use ts_rs::TS;
            use flowjs_rs::Flow;
            let ts: Vec<String> = vec![ $( <$ty as TS>::decl($ts_cfg) ),* ];
            let flow: Vec<String> = vec![ $( <$ty as Flow>::decl($flow_cfg) ),* ];
            (ts, flow)
        }};
    }

    const ALIASES: &[TypeAlias] = &[
        TypeAlias {
            name: "AttrPredicate",
            target: "Predicate",
        },
        TypeAlias {
            name: "AttrOp",
            target: "PredicateOp",
        },
    ];

    // All engine WASM exports — fn-pointer descriptors auto-generated by #[wasm_export] in wasm.rs.
    const WASM_FNS: &[WasmFn] = &[
        crate::index::_WASM_JS_BRIDGE_DECLARE,
        crate::index::_WASM_JS_BRIDGE_PARSE_MANIFEST,
        crate::index::_WASM_JS_BRIDGE_PARSE_SELECTOR,
        crate::index::_WASM_JS_BRIDGE_SELECT,
        crate::index::_WASM_JS_BRIDGE_VALIDATE,
        crate::index::_WASM_JS_BRIDGE_DIFF_ANNOTATIONS,
        crate::index::_WASM_JS_BRIDGE_EXTRACT_PATTERN,
        crate::index::_WASM_JS_BRIDGE_SUGGEST_REPAIRS,
        crate::index::_WASM_JS_BRIDGE_SIDECAR_FOR,
        crate::index::_WASM_JS_BRIDGE_SOURCE_CANDIDATES,
        crate::index::_WASM_JS_BRIDGE_EXTRACT_BIND,
        crate::index::_WASM_JS_BRIDGE_RESOLVE_BIND_NAME,
        crate::index::_WASM_JS_BRIDGE_EXTRACT_AQL_SYMBOLS,
        crate::index::_WASM_JS_BRIDGE_MEASURE_COMPRESSION,
    ];

    #[test]
    fn generate_npm_files() {
        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
        let ts_cfg = ts_rs::Config::default();
        let flow_cfg = flowjs_rs::Config::default();

        // Single type list → both TS and Flow declarations
        let (ts_decls, flow_decls) = collect_decls!(
            &ts_cfg,
            &flow_cfg,
            [
                // Newtypes (must come first — referenced by other types)
                amql_selector::TagName,
                amql_selector::AttrName,
                amql_mutate::NodeKind,
                amql_mutate::RelativePath,
                crate::Binding,
                crate::Scope,
                crate::CodeElementName,
                crate::SelectorStr,
                // serde_json::Value → JsonValue
                serde_json::Value,
                // Predicate types
                amql_predicates::PredicateOp,
                amql_predicates::PredicateValue,
                amql_predicates::Predicate,
                amql_predicates::Token,
                // Selector types
                amql_selector::Combinator,
                amql_selector::CompoundSelector,
                amql_selector::SelectorAst,
                // Mutation types
                amql_mutate::NodeRef,
                amql_mutate::InsertPosition,
                amql_mutate::MutationResult,
                amql_mutate::RemoveResult,
                // Engine types
                crate::Annotation,
                crate::FileEntry,
                crate::DeclareConfig,
                crate::DeclareTag,
                crate::DeclareAttr,
                crate::DeclareExtractor,
                crate::Manifest,
                crate::TagDefinition,
                crate::AttrDefinition,
                crate::AttrType,
                crate::ExtractorConfig,
                crate::DiffResult,
                crate::DiffEntry,
                crate::DiffChange,
                crate::Pattern,
                crate::PatternResult,
                crate::AttrSummary,
                crate::Delta,
                crate::ValidationResult,
                crate::ValidationLevel,
                crate::RepairSuggestion,
                crate::CompressionResult,
                crate::FileCompression,
                crate::SourceEntry,
                crate::AqlSymbol,
            ]
        );

        // Stem derived from src/wasm.rs → "wasm"
        let stem = wasm_js_bridge::file_to_stem(WASM_FNS[0].file);

        let dts = generate_index_dts(&ts_decls, ALIASES, &[], WASM_FNS);
        std::fs::write(dir.join(format!("{stem}.d.ts")), dts)
            .expect("Failed to write .d.ts");

        let opaque = &[
            OpaqueType { name: "TagName", bound: Some("string") },
            OpaqueType { name: "AttrName", bound: Some("string") },
            OpaqueType { name: "NodeKind", bound: Some("string") },
            OpaqueType { name: "RelativePath", bound: Some("string") },
            OpaqueType { name: "Binding", bound: Some("string") },
            OpaqueType { name: "Scope", bound: Some("string") },
            OpaqueType { name: "CodeElementName", bound: Some("string") },
            OpaqueType { name: "SelectorStr", bound: Some("string") },
            OpaqueType { name: "Manifest", bound: None },
        ];
        let flow = generate_index_flow(&flow_decls, ALIASES, &[], WASM_FNS, opaque);
        std::fs::write(dir.join(format!("{stem}.js.flow")), flow)
            .expect("Failed to write .js.flow");
    }
}