scryer-engine 0.3.0

use std::path::PathBuf;

/// Intermediate representation of an AST lexical scope extracted before database insertion.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RawScope {
    /// Zero-based local scope index within the file.
    pub local_id: usize,
    /// Reference to the enclosing parent scope's `local_id`.
    pub parent_local_id: Option<usize>,
    /// Lexical category: `"module"`, `"class"`, `"function"`, `"closure"`, `"block"`.
    pub scope_kind: String,
    /// Zero-based byte offset of start of scope.
    pub start_byte: usize,
    /// Zero-based byte offset of end of scope.
    pub end_byte: usize,
    /// 1-indexed line number where the scope starts.
    pub start_line: u32,
    /// 1-indexed line number where the scope ends.
    pub end_line: u32,
}

/// Intermediate representation of a code symbol declaration extracted before database insertion.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RawSymbol {
    /// Local scope index within the file containing this symbol declaration.
    pub scope_local_id: Option<usize>,
    /// Bare symbol identifier (e.g. `Scanner`).
    pub name: String,
    /// Hierarchically qualified symbol path (e.g. `crate::scanner::Scanner`).
    pub qualified_name: String,
    /// Kind: `"fn"`, `"struct"`, `"trait"`, `"enum"`, `"type"`, `"const"`, `"mod"`.
    pub kind: String,
    /// Normalized visibility modifier: `"public"`, `"crate"`, `"private"`.
    pub visibility: String,
    /// Condensed declaration signature (omitting body).
    pub signature: String,
    /// Associated doc comments / doc attributes formatted as Markdown.
    pub docstring: Option<String>,
    /// Zero-based byte offset of start of symbol.
    pub start_byte: usize,
    /// Zero-based byte offset of end of symbol.
    pub end_byte: usize,
    /// 1-indexed line number where the symbol starts.
    pub start_line: u32,
    /// 1-indexed line number where the symbol ends.
    pub end_line: u32,
}

/// How a reference was tied to its target.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Via {
    /// Through an explicit path, an import, the project's only definition of the name or the
    /// file's own scopes, and the target is the only symbol that matches.
    Exact,
    /// Matched by name only: a method call on an unknown receiver, or a bare name that several
    /// symbols share.
    #[default]
    Name,
    /// Found by scanning the tokens of a macro invocation, then matched by name.
    Macro,
}

impl Via {
    /// The inverse of [`Via::as_str`]; anything else is a name match.
    pub fn parse(text: &str) -> Via {
        match text {
            "exact" => Via::Exact,
            "macro" => Via::Macro,
            _ => Via::Name,
        }
    }

    pub fn as_str(self) -> &'static str {
        match self {
            Via::Exact => "exact",
            Via::Name => "name",
            Via::Macro => "macro",
        }
    }
}

/// Intermediate representation of a symbol reference extracted before database insertion.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RawSymbolReference {
    /// Qualified name of the target symbol being referenced, or bare symbol name.
    pub target_symbol_name: String,
    /// Reference role: "call", "type_annotation", "read", "write", "import".
    pub role: String,
    /// Zero-based byte offset of start of reference.
    pub start_byte: usize,
    /// Zero-based byte offset of end of reference.
    pub end_byte: usize,
    /// 1-indexed line number where the reference occurs.
    pub line_number: u32,
    /// How the target was chosen. Ingest downgrades `Exact` to `Name` when several symbols
    /// still match.
    pub via: Via,
}

/// Intermediate representation of a code graph edge between two symbols.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RawCodeGraphEdge {
    /// Qualified or bare name of the source (caller/origin) symbol.
    pub source_symbol_name: String,
    /// Qualified or bare name of the target (callee/destination) symbol.
    pub target_symbol_name: String,
    /// Edge type: "calls", "implements", "instantiates", "imports".
    pub edge_type: String,
}

/// Fully extracted and parsed file metadata and syntactic entities.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParsedFilePayload {
    /// Normalized path relative to the project root.
    pub relative_path: PathBuf,
    /// 256-bit BLAKE3 hash of file content.
    pub content_hash: String,
    /// Canonical language identifier (e.g. `"rust"`).
    pub language: String,
    /// Total lines in the file.
    pub line_count: u32,
    /// File size in bytes.
    pub byte_size: usize,
    /// Extracted scopes in topological/parent-first order.
    pub scopes: Vec<RawScope>,
    /// Extracted symbol declarations.
    pub symbols: Vec<RawSymbol>,
    /// Extracted symbol usages / references.
    pub references: Vec<RawSymbolReference>,
    /// Extracted call graph and dependency edges.
    pub edges: Vec<RawCodeGraphEdge>,
    /// The file parsed with syntax errors, so code around them may be missing from the index.
    pub syntax_errors: bool,
}

/// Structural representation of a type contract extracted from AST and symbol tables.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RawTypeContract {
    pub found: bool,
    pub type_name: String,
    pub kind: Option<String>,
    pub signature: Option<String>,
    pub docstring: Option<String>,
    pub file_path: Option<String>,
    pub members: Vec<String>,
}