vectorless 0.1.21

// Copyright (c) 2026 vectorless developers
// SPDX-License-Identifier: Apache-2.0

//! Public API types for the client module.
//!
//! This module contains all types exposed in the public API.

use serde::{Deserialize, Serialize};
use std::path::PathBuf;

use crate::document::DocumentTree;
use crate::parser::DocumentFormat;

// ============================================================
// Document Types
// ============================================================

/// An indexed document with its tree structure and metadata.
#[derive(Debug, Clone)]
pub struct IndexedDocument {
    /// Unique document identifier.
    pub id: String,

    /// Document format.
    pub format: DocumentFormat,

    /// Document name/title.
    pub name: String,

    /// Document description (generated by LLM).
    pub description: Option<String>,

    /// Source file path.
    pub source_path: Option<PathBuf>,

    /// Page count (for PDFs).
    pub page_count: Option<usize>,

    /// Line count (for text files).
    pub line_count: Option<usize>,

    /// The document tree structure.
    pub tree: Option<DocumentTree>,

    /// Per-page content (for PDFs).
    pub pages: Vec<PageContent>,
}

impl IndexedDocument {
    /// Create a new indexed document.
    pub fn new(id: impl Into<String>, format: DocumentFormat) -> Self {
        Self {
            id: id.into(),
            format,
            name: String::new(),
            description: None,
            source_path: None,
            page_count: None,
            line_count: None,
            tree: None,
            pages: Vec::new(),
        }
    }

    /// Set the document name.
    pub fn with_name(mut self, name: impl Into<String>) -> Self {
        self.name = name.into();
        self
    }

    /// Set the document description.
    pub fn with_description(mut self, desc: impl Into<String>) -> Self {
        self.description = Some(desc.into());
        self
    }

    /// Set the source path.
    pub fn with_source_path(mut self, path: impl Into<PathBuf>) -> Self {
        self.source_path = Some(path.into());
        self
    }

    /// Set the page count.
    pub fn with_page_count(mut self, count: usize) -> Self {
        self.page_count = Some(count);
        self
    }

    /// Set the line count.
    pub fn with_line_count(mut self, count: usize) -> Self {
        self.line_count = Some(count);
        self
    }

    /// Set the document tree.
    pub fn with_tree(mut self, tree: DocumentTree) -> Self {
        self.tree = Some(tree);
        self
    }

    /// Add a page content.
    pub fn add_page(&mut self, page: usize, content: impl Into<String>) {
        self.pages.push(PageContent {
            page,
            content: content.into(),
        });
    }

    /// Check if the tree is loaded.
    pub fn is_loaded(&self) -> bool {
        self.tree.is_some()
    }
}

/// Content for a single page.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PageContent {
    /// Page number (1-based).
    pub page: usize,

    /// Page text content.
    pub content: String,
}

// ============================================================
// Index Types
// ============================================================

/// Document indexing behavior mode.
///
/// Controls how the indexer handles existing documents and re-indexing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum IndexMode {
    /// Default mode - skip if already indexed.
    ///
    /// If a document with the same source has already been indexed,
    /// the operation is skipped and the existing document ID is returned.
    #[default]
    Default,

    /// Force re-indexing.
    ///
    /// Always re-index the document, even if it has been indexed before.
    /// A new document ID is generated.
    Force,

    /// Incremental mode - only re-index changed files.
    ///
    /// Re-index only if the file has been modified since the last index.
    /// For content/bytes sources, this behaves like [`IndexMode::Default`].
    Incremental,
}

/// Options for indexing a document.
#[derive(Debug, Clone)]
pub struct IndexOptions {
    /// Indexing mode.
    pub mode: IndexMode,

    /// Whether to generate summaries using LLM.
    pub generate_summaries: bool,

    /// Whether to include node text in the tree.
    pub include_text: bool,

    /// Whether to generate node IDs.
    pub generate_ids: bool,

    /// Whether to generate document description.
    pub generate_description: bool,
}

impl Default for IndexOptions {
    fn default() -> Self {
        Self {
            mode: IndexMode::Default,
            generate_summaries: true,
            include_text: true,
            generate_ids: true,
            generate_description: false,
        }
    }
}

impl IndexOptions {
    /// Create new index options with defaults.
    pub fn new() -> Self {
        Self::default()
    }

    /// Enable summary generation.
    pub fn with_summaries(mut self) -> Self {
        self.generate_summaries = true;
        self
    }

    /// Enable document description generation.
    pub fn with_description(mut self) -> Self {
        self.generate_description = true;
        self
    }

    /// Set the indexing mode.
    ///
    /// # Modes
    ///
    /// - [`IndexMode::Default`] - Skip if already indexed
    /// - [`IndexMode::Force`] - Always re-index
    /// - [`IndexMode::Incremental`] - Only re-index changed files
    pub fn with_mode(mut self, mode: IndexMode) -> Self {
        self.mode = mode;
        self
    }
}

// ============================================================
// Index Result Types
// ============================================================

/// Result of a document indexing operation.
#[derive(Debug, Clone)]
pub struct IndexResult {
    /// Indexed items.
    pub items: Vec<IndexItem>,
}

impl IndexResult {
    /// Create a new index result.
    pub fn new(items: Vec<IndexItem>) -> Self {
        Self { items }
    }

    /// Get the single document ID (convenience for single-document indexing).
    pub fn doc_id(&self) -> Option<&str> {
        if self.items.len() == 1 {
            Some(&self.items[0].doc_id)
        } else {
            None
        }
    }

    /// Check if the result is empty.
    pub fn is_empty(&self) -> bool {
        self.items.is_empty()
    }

    /// Get the number of indexed items.
    pub fn len(&self) -> usize {
        self.items.len()
    }
}

/// A single indexed document item.
#[derive(Debug, Clone)]
pub struct IndexItem {
    /// The unique document ID.
    pub doc_id: String,
    /// The document name.
    pub name: String,
    /// The document format.
    pub format: DocumentFormat,
}

impl IndexItem {
    /// Create a new index item.
    pub fn new(
        doc_id: impl Into<String>,
        name: impl Into<String>,
        format: DocumentFormat,
    ) -> Self {
        Self {
            doc_id: doc_id.into(),
            name: name.into(),
            format,
        }
    }
}

// ============================================================
// Query Types
// ============================================================

/// Result of a document query.
#[derive(Debug, Clone)]
pub struct QueryResult {
    /// The document ID.
    pub doc_id: String,

    /// Matching node IDs.
    pub node_ids: Vec<String>,

    /// Retrieved content.
    pub content: String,

    /// Relevance score.
    pub score: f32,
}

impl QueryResult {
    /// Create a new query result.
    pub fn new(doc_id: impl Into<String>) -> Self {
        Self {
            doc_id: doc_id.into(),
            node_ids: Vec::new(),
            content: String::new(),
            score: 0.0,
        }
    }

    /// Check if the result is empty.
    pub fn is_empty(&self) -> bool {
        self.node_ids.is_empty()
    }

    /// Get the number of results.
    pub fn len(&self) -> usize {
        self.node_ids.len()
    }
}

// ============================================================
// Document Info Types
// ============================================================

/// Document info for listing.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DocumentInfo {
    /// Document ID.
    pub id: String,

    /// Document name.
    pub name: String,

    /// Document format.
    pub format: String,

    /// Document description.
    pub description: Option<String>,

    /// Page count (for PDFs).
    pub page_count: Option<usize>,

    /// Line count (for text files).
    pub line_count: Option<usize>,
}

impl DocumentInfo {
    /// Create a new document info.
    pub fn new(id: impl Into<String>, name: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            name: name.into(),
            format: String::new(),
            description: None,
            page_count: None,
            line_count: None,
        }
    }

    /// Set the format.
    pub fn with_format(mut self, format: impl Into<String>) -> Self {
        self.format = format.into();
        self
    }
}

// ============================================================
// Error Types
// ============================================================

/// Client error types.
#[derive(Debug, Clone, thiserror::Error)]
pub enum ClientError {
    /// Document not found.
    #[error("Document not found: {0}")]
    NotFound(String),

    /// Invalid operation.
    #[error("Invalid operation: {0}")]
    InvalidOperation(String),

    /// Configuration error.
    #[error("Configuration error: {0}")]
    Config(String),

    /// Timeout error.
    #[error("Operation timed out")]
    Timeout,
}

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

    #[test]
    fn test_indexed_document() {
        let doc = IndexedDocument::new("doc-1", DocumentFormat::Markdown)
            .with_name("Test Document")
            .with_description("A test document");

        assert_eq!(doc.id, "doc-1");
        assert_eq!(doc.name, "Test Document");
        assert!(doc.tree.is_none());
    }

    #[test]
    fn test_index_options() {
        let options = IndexOptions::new()
            .with_summaries()
            .with_mode(IndexMode::Force);

        assert!(options.generate_summaries);
        assert_eq!(options.mode, IndexMode::Force);
    }

    #[test]
    fn test_query_result() {
        let result = QueryResult::new("doc-1");
        assert!(result.is_empty());
        assert_eq!(result.len(), 0);
    }

    #[test]
    fn test_document_info() {
        let info = DocumentInfo::new("doc-1", "Test").with_format("markdown");

        assert_eq!(info.id, "doc-1");
        assert_eq!(info.format, "markdown");
    }

    #[test]
    fn test_index_result() {
        let item = IndexItem::new("doc-1", "Test", DocumentFormat::Markdown);
        let result = IndexResult::new(vec![item]);

        assert_eq!(result.doc_id(), Some("doc-1"));
        assert_eq!(result.len(), 1);
        assert!(!result.is_empty());
    }

    #[test]
    fn test_index_result_empty() {
        let result = IndexResult::new(vec![]);
        assert!(result.is_empty());
        assert_eq!(result.doc_id(), None);
    }

    #[test]
    fn test_index_result_multiple() {
        let items = vec![
            IndexItem::new("doc-1", "A", DocumentFormat::Markdown),
            IndexItem::new("doc-2", "B", DocumentFormat::Pdf),
        ];
        let result = IndexResult::new(items);
        assert_eq!(result.len(), 2);
        assert_eq!(result.doc_id(), None);
    }
}