amql_engine/

sidecar.rs

//! Sidecar file location strategies.
//!
//! A `SidecarLocator` maps between source files and their `.aqm` annotation
//! sidecars. The default strategy is colocation (sidecar next to source).
//! Alternative strategies allow centralized annotation directories.

use crate::types::{Binding, ProjectRoot, RelativePath, TagName};
use std::path::{Path, PathBuf};

// ---------------------------------------------------------------------------
// Pure path/string helpers (no filesystem, no feature gates)
// ---------------------------------------------------------------------------

/// Source extensions the engine's resolver registry handles.
pub const SOURCE_EXTENSIONS: &[&str] =
    &[".rs", ".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs", ".go"];

/// Derive the colocated sidecar path from a source path.
/// `src/api.ts` → `src/api.aqm`
#[must_use = "returns the derived sidecar path"]
pub fn sidecar_for_colocated(source: &RelativePath) -> RelativePath {
    let p = Path::new(AsRef::<str>::as_ref(source));
    let stem = p.file_stem().unwrap_or_default().to_string_lossy();
    match p.parent().filter(|p| !p.as_os_str().is_empty()) {
        Some(parent) => RelativePath::from(format!("{}/{stem}.aqm", parent.to_string_lossy())),
        None => RelativePath::from(format!("{stem}.aqm")),
    }
}

/// Candidate source paths for a sidecar. Inverse of `sidecar_for_colocated`.
pub fn source_candidates(sidecar: &RelativePath) -> Vec<RelativePath> {
    let p = Path::new(AsRef::<str>::as_ref(sidecar));
    let stem = p.file_stem().unwrap_or_default().to_string_lossy();
    let parent = p.parent().filter(|p| !p.as_os_str().is_empty());
    SOURCE_EXTENSIONS
        .iter()
        .map(|ext| {
            RelativePath::from(match parent {
                Some(dir) => format!("{}/{stem}{ext}", dir.to_string_lossy()),
                None => format!("{stem}{ext}"),
            })
        })
        .collect()
}

/// Extract the `bind="..."` value from a single line of AQL XML.
pub fn extract_bind_from_line(line: &str) -> Option<Binding> {
    let rest = line.split_once("bind=")?.1;
    let quote = rest.as_bytes().first()?;
    if *quote != b'"' && *quote != b'\'' {
        return None;
    }
    let inner = &rest[1..];
    let end = inner.find(*quote as char)?;
    Some(Binding::from(&inner[..end]))
}

/// Resolve qualified bindings: `Foo.bar` → `bar`.
///
/// Semantically returns a `CodeElementName`, but since it borrows a substring
/// of the input binding, the return type remains `&str`.
pub fn resolve_bind_name(bind: &Binding) -> &str {
    let s: &str = bind.as_ref();
    s.rsplit('.').next().unwrap_or(s)
}

/// A symbol extracted from an `.aqm` file for editor outline/navigation.
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "flow", derive(flowjs_rs::Flow))]
#[cfg_attr(feature = "ts", ts(export))]
#[cfg_attr(feature = "flow", flow(export))]
#[derive(Debug, Clone, serde::Serialize)]
pub struct AqlSymbol {
    /// The `bind="..."` value.
    pub binding: Binding,
    /// The XML element tag name (e.g. "controller", "parser").
    pub tag: TagName,
    /// 0-based line number in the document.
    pub line: usize,
}

/// Extract symbols from `.aqm` document text for editor features (outline, go-to).
pub fn extract_aql_symbols(text: &str) -> Vec<AqlSymbol> {
    text.lines()
        .enumerate()
        .filter_map(|(line, content)| {
            let tag = extract_tag_name(content)?;
            let binding = extract_bind_from_line(content)?;
            Some(AqlSymbol { binding, tag, line })
        })
        .collect()
}

fn extract_tag_name(line: &str) -> Option<TagName> {
    let rest = line.trim_start().strip_prefix('<')?;
    let end = rest.find(|c: char| c.is_whitespace() || c == '/' || c == '>')?;
    let name = &rest[..end];
    if name.is_empty() || name.starts_with('!') || name.starts_with('?') {
        return None;
    }
    Some(TagName::from(name))
}

// ---------------------------------------------------------------------------
// Locator trait
// ---------------------------------------------------------------------------

/// Strategy for locating `.aqm` sidecar files relative to source files.
///
/// Not sealed — plugins and users can implement custom locators.
pub trait SidecarLocator: Send + Sync {
    /// Discover all sidecar files and their corresponding source-relative paths.
    fn discover(&self, project_root: &ProjectRoot) -> Vec<(PathBuf, RelativePath)>;

    /// Given a source-relative path, return the sidecar file path (relative to project root).
    fn sidecar_for(&self, source: &RelativePath) -> RelativePath;
}

/// Default strategy: sidecar lives next to its source file with `.aqm` extension.
/// `src/api.ts` → `src/api.aqm`
#[cfg(feature = "fs")]
pub struct ColocatedLocator;

#[cfg(feature = "fs")]
impl SidecarLocator for ColocatedLocator {
    fn discover(&self, project_root: &ProjectRoot) -> Vec<(PathBuf, RelativePath)> {
        let aql_paths = crate::store::glob_aql_files(project_root);
        let dir_listings = precompute_dir_listings(&aql_paths);

        aql_paths
            .into_iter()
            .filter_map(|sidecar_path| {
                let stem = sidecar_path.file_stem()?.to_string_lossy().to_string();
                let parent = sidecar_path.parent()?;

                let source_path = dir_listings
                    .get(parent)
                    .and_then(|files| find_source_in_listing(files, &stem))
                    .unwrap_or_else(|| parent.join(&stem));

                let rel_source = crate::paths::relative(project_root, &source_path);
                Some((sidecar_path, rel_source))
            })
            .collect()
    }

    fn sidecar_for(&self, source: &RelativePath) -> RelativePath {
        let p = Path::new(AsRef::<str>::as_ref(source));
        let stem = p.file_stem().unwrap_or_default().to_string_lossy();
        RelativePath::from(match p.parent().filter(|p| !p.as_os_str().is_empty()) {
            Some(parent) => format!("{}/{stem}.aqm", parent.to_string_lossy()),
            None => format!("{stem}.aqm"),
        })
    }
}

/// Centralized strategy: all sidecars live under a single directory,
/// mirroring the source tree structure.
/// With `base = ".annotations"`: `src/api.ts` → `.annotations/src/api.aqm`
#[cfg(feature = "fs")]
pub struct DirectoryLocator {
    /// Directory (relative to project root) containing all sidecar files.
    pub base: RelativePath,
}

#[cfg(feature = "fs")]
impl SidecarLocator for DirectoryLocator {
    fn discover(&self, project_root: &ProjectRoot) -> Vec<(PathBuf, RelativePath)> {
        let base_dir = project_root.join(AsRef::<Path>::as_ref(&self.base));
        if !base_dir.is_dir() {
            return vec![];
        }

        let aql_paths = crate::store::glob_aql_files(&base_dir);
        let dir_listings = precompute_dir_listings_for_project(project_root, &base_dir, &aql_paths);

        aql_paths
            .into_iter()
            .filter_map(|sidecar_path| {
                // Strip base directory to get the mirrored source path
                let rel_in_base = sidecar_path.strip_prefix(&base_dir).ok()?;
                let stem = rel_in_base.file_stem()?.to_string_lossy().to_string();
                let parent = rel_in_base.parent().filter(|p| !p.as_os_str().is_empty());

                // Resolve the actual source file (with extension) from the project root
                let source_dir = match parent {
                    Some(p) => project_root.join(p),
                    None => project_root.to_path_buf(),
                };
                let source_path = dir_listings
                    .get(&source_dir)
                    .and_then(|files| find_source_in_listing(files, &stem))
                    .unwrap_or_else(|| {
                        // Fallback: use stem without extension
                        match parent {
                            Some(p) => project_root.join(p).join(&stem),
                            None => project_root.join(&stem),
                        }
                    });

                let rel_source = crate::paths::relative(project_root, &source_path);
                Some((sidecar_path, rel_source))
            })
            .collect()
    }

    fn sidecar_for(&self, source: &RelativePath) -> RelativePath {
        let p = Path::new(AsRef::<str>::as_ref(source));
        let stem = p.file_stem().unwrap_or_default().to_string_lossy();
        let sidecar_name = match p.parent().filter(|p| !p.as_os_str().is_empty()) {
            Some(parent) => format!("{}/{stem}.aqm", parent.to_string_lossy()),
            None => format!("{stem}.aqm"),
        };
        RelativePath::from(format!("{}/{sidecar_name}", self.base))
    }
}

// ---------------------------------------------------------------------------
// In-memory locator for builds without filesystem access
// ---------------------------------------------------------------------------

/// Stub locator that derives sidecar paths from source paths without filesystem access.
/// Used when the `fs` feature is disabled (e.g. WASM builds).
#[cfg(not(feature = "fs"))]
pub(crate) struct InMemoryLocator;

#[cfg(not(feature = "fs"))]
impl SidecarLocator for InMemoryLocator {
    fn discover(&self, _project_root: &ProjectRoot) -> Vec<(PathBuf, RelativePath)> {
        vec![]
    }

    fn sidecar_for(&self, source: &RelativePath) -> RelativePath {
        let p = Path::new(AsRef::<str>::as_ref(source));
        let stem = p.file_stem().unwrap_or_default().to_string_lossy();
        RelativePath::from(match p.parent().filter(|p| !p.as_os_str().is_empty()) {
            Some(parent) => format!("{}/{stem}.aqm", parent.to_string_lossy()),
            None => format!("{stem}.aqm"),
        })
    }
}

// ---------------------------------------------------------------------------
// Filesystem helpers (only with fs feature)
// ---------------------------------------------------------------------------

#[cfg(feature = "fs")]
use rustc_hash::FxHashMap;

/// Precompute directory listings for all unique parent directories of sidecar paths.
#[cfg(feature = "fs")]
fn precompute_dir_listings(paths: &[PathBuf]) -> FxHashMap<PathBuf, Vec<PathBuf>> {
    let mut map: FxHashMap<PathBuf, Vec<PathBuf>> = FxHashMap::default();
    for path in paths {
        if let Some(parent) = path.parent() {
            map.entry(parent.to_path_buf())
                .or_insert_with(|| read_dir_listing(parent));
        }
    }
    map
}

/// Precompute directory listings for project source dirs corresponding to sidecar paths.
/// Maps sidecar parent dirs (under `base_dir`) to project source dirs.
#[cfg(feature = "fs")]
fn precompute_dir_listings_for_project(
    project_root: &ProjectRoot,
    base_dir: &Path,
    sidecar_paths: &[PathBuf],
) -> FxHashMap<PathBuf, Vec<PathBuf>> {
    let mut map: FxHashMap<PathBuf, Vec<PathBuf>> = FxHashMap::default();
    for path in sidecar_paths {
        if let Some(parent) = path.parent() {
            // Map .annotations/src/ → <project_root>/src/
            let source_dir = match parent.strip_prefix(base_dir) {
                Ok(rel) if !rel.as_os_str().is_empty() => project_root.join(rel),
                _ => project_root.to_path_buf(),
            };
            map.entry(source_dir.clone())
                .or_insert_with(|| read_dir_listing(&source_dir));
        }
    }
    map
}

/// List files in a directory. Returns empty vec on I/O error.
#[cfg(feature = "fs")]
fn read_dir_listing(dir: &Path) -> Vec<PathBuf> {
    std::fs::read_dir(dir)
        .ok()
        .map(|entries| {
            entries
                .flatten()
                .map(|e| e.path())
                .filter(|p| p.is_file())
                .collect()
        })
        .unwrap_or_default()
}

/// Find a source file whose stem matches `stem` from a pre-computed file listing.
#[cfg(feature = "fs")]
fn find_source_in_listing(files: &[PathBuf], stem: &str) -> Option<PathBuf> {
    files
        .iter()
        .find(|path| {
            path.file_stem()
                .is_some_and(|s| s.to_string_lossy() == stem)
                && path.extension().is_some_and(|ext| ext != "aqm")
        })
        .cloned()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    #[cfg(feature = "fs")]
    fn colocated_sidecar_for() {
        // Arrange
        let locator = ColocatedLocator;

        // Act and Assert
        assert_eq!(
            locator.sidecar_for(&RelativePath::from("src/api.ts")),
            "src/api.aqm",
            "should derive colocated sidecar path"
        );
        assert_eq!(
            locator.sidecar_for(&RelativePath::from("lib.rs")),
            "lib.aqm",
            "should handle root-level files"
        );
    }

    #[test]
    #[cfg(feature = "fs")]
    fn directory_sidecar_for() {
        // Arrange
        let locator = DirectoryLocator {
            base: RelativePath::from(".annotations"),
        };

        // Act and Assert
        assert_eq!(
            locator.sidecar_for(&RelativePath::from("src/api.ts")),
            ".annotations/src/api.aqm",
            "should place sidecar under base directory"
        );
        assert_eq!(
            locator.sidecar_for(&RelativePath::from("lib.rs")),
            ".annotations/lib.aqm",
            "should handle root-level files under base"
        );
    }

    #[test]
    fn free_fn_sidecar_for_colocated() {
        // Act and Assert
        assert_eq!(
            sidecar_for_colocated(&RelativePath::from("src/api.ts")),
            "src/api.aqm",
            "should derive colocated sidecar path"
        );
        assert_eq!(
            sidecar_for_colocated(&RelativePath::from("lib.rs")),
            "lib.aqm",
            "should handle root-level files"
        );
    }

    #[test]
    fn free_fn_source_candidates() {
        // Act
        let candidates = source_candidates(&RelativePath::from("src/api.aqm"));

        // Assert
        assert_eq!(
            candidates.len(),
            SOURCE_EXTENSIONS.len(),
            "should produce one candidate per extension"
        );
        assert_eq!(candidates[0], "src/api.rs", "first candidate should be .rs");
        assert_eq!(
            candidates[1], "src/api.ts",
            "second candidate should be .ts"
        );
    }

    #[test]
    fn extract_bind_double_quotes() {
        // Act and Assert
        assert_eq!(
            extract_bind_from_line(r#"<parser bind="parse_selector" owner="@engine">"#),
            Some(Binding::from("parse_selector")),
            "should extract bind value from double-quoted attribute"
        );
    }

    #[test]
    fn extract_bind_single_quotes() {
        // Act and Assert
        assert_eq!(
            extract_bind_from_line("<parser bind='parse_selector'>"),
            Some(Binding::from("parse_selector")),
            "should extract bind value from single-quoted attribute"
        );
    }

    #[test]
    fn extract_bind_no_match() {
        // Act and Assert
        assert_eq!(
            extract_bind_from_line("<parser owner=\"@engine\">"),
            None,
            "should return None when no bind attribute"
        );
    }

    #[test]
    fn resolve_bind_name_simple() {
        // Act and Assert
        assert_eq!(
            resolve_bind_name(&Binding::from("parse_selector")),
            "parse_selector",
            "should return name unchanged when not qualified"
        );
    }

    #[test]
    fn resolve_bind_name_qualified() {
        // Act and Assert
        assert_eq!(
            resolve_bind_name(&Binding::from("Foo.bar")),
            "bar",
            "should return last segment of qualified binding"
        );
    }
}