kglite 0.18.0

//! Schema introspection — exploring graph structure.
//!
//! All functions take `&DirGraph` and return Rust structs. PyO3 conversion
//! happens in `graph::pyapi`.
//!
//! Submodules:
//! - [`capabilities`] — TypeCapabilities + endpoint-type discovery
//! - [`connectivity`] — type connectivity triples + neighbors_from_triples
//! - [`schema_overview`] — schema / property / neighbors / sample / join candidates
//! - [`describe`] — XML describe() entry point + inventory builders + XML writers
//! - [`skills_section`] — the agent-guidance sections of a description
//! - [`topics`] — tier-3 Cypher + Fluent topic detail writers
//! - [`bug_report`] / [`debugging`] / [`reporting`] — bug-report writer, debug
//!   dumps, structured mutation reports

pub mod bug_report;
pub mod capabilities;
pub mod connectivity;
pub mod debugging;
pub mod describe;
pub(crate) mod embeddings_view;
pub mod reporting;
pub mod schema_overview;
pub(crate) mod skills_section;
pub mod topics;

use crate::datatypes::values::Value;
use crate::graph::schema::DirGraph;
use crate::graph::storage::GraphRead;
use std::collections::HashMap;

pub use connectivity::{
    compute_type_connectivity, derive_edge_counts_from_triples, sort_connectivity_triples,
};

pub struct ConnectionTypeStats {
    pub connection_type: String,
    pub count: usize,
    pub source_types: Vec<String>,
    pub target_types: Vec<String>,
    pub property_names: Vec<String>,
}

pub struct NodeTypeOverview {
    pub count: usize,
    pub properties: HashMap<String, String>,
}

pub struct SchemaOverview {
    pub node_types: Vec<(String, NodeTypeOverview)>,
    pub connection_types: Vec<ConnectionTypeStats>,
    pub indexes: Vec<String>,
    pub node_count: usize,
    pub edge_count: usize,
}

/// Serialize a [`SchemaOverview`] to its canonical JSON shape — the single
/// source of truth for the agent-facing schema document. Every JSON binding
/// (the C ABI's `kglite_compute_schema_json`, future REST/gRPC) renders the
/// schema through this one function so the field names + shape can't drift
/// between bindings. Re-exported as `kglite::api::schema_overview_to_json`.
pub fn schema_overview_to_json(schema: &SchemaOverview) -> serde_json::Value {
    let node_types: Vec<serde_json::Value> = schema
        .node_types
        .iter()
        .map(|(name, ov)| {
            serde_json::json!({
                "type": name,
                "count": ov.count,
                "properties": ov.properties,
            })
        })
        .collect();
    let connection_types: Vec<serde_json::Value> = schema
        .connection_types
        .iter()
        .map(|c| {
            serde_json::json!({
                "type": c.connection_type,
                "count": c.count,
                "source_types": c.source_types,
                "target_types": c.target_types,
                "property_names": c.property_names,
            })
        })
        .collect();
    serde_json::json!({
        "node_types": node_types,
        "connection_types": connection_types,
        "indexes": schema.indexes,
        "node_count": schema.node_count,
        "edge_count": schema.edge_count,
    })
}

pub struct PropertyStatInfo {
    pub property_name: String,
    pub type_string: String,
    pub non_null: usize,
    pub unique: usize,
    pub values: Option<Vec<Value>>,
    /// One example value when `values` is None (high-cardinality property), so
    /// the schema still shows what a property like `file_path` *looks like*
    /// instead of leaving an agent to guess from the name.
    pub sample: Option<Value>,
    /// `true` when `unique` / `values` are NOT exhaustive — the population was
    /// sampled (only some nodes scanned) or the distinct-value set hit its cap.
    /// Consumers must present these as lower bounds (`unique="5+"`), never as
    /// exact counts. `false` means a full scan enumerated every distinct value.
    pub approx: bool,
}

/// Node-count ceiling for exact property stats. At or below this, a full scan
/// enumerates every distinct value cheaply (the value set is capped, so memory
/// stays bounded); above it, sampling kicks in and stats are marked `approx`.
/// Sampling exists for Wikidata-scale types, not ordinary code/data graphs.
pub const EXACT_PROPERTY_STATS_MAX_NODES: usize = 200_000;

#[derive(Clone)]
pub struct NeighborConnection {
    pub connection_type: String,
    pub other_type: String,
    pub count: usize,
}

#[derive(Clone)]
pub struct NeighborsSchema {
    pub outgoing: Vec<NeighborConnection>,
    pub incoming: Vec<NeighborConnection>,
}

/// Scale classification for adaptive describe output.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GraphScale {
    /// 0-15 core types: full inline detail.
    Small,
    /// 16-200 core types: compact inventory listing.
    Medium,
    /// 201-5000 core types: top-N types with summary.
    Large,
    /// 5001+ core types: statistical summary, search required.
    Extreme,
}

/// Node types a description enumerates: every live type except the system
/// labels ([`crate::graph::schema::SYSTEM_LABELS`]), paired with its live-node
/// count. Every listing *and* every count rendered beside one comes from here,
/// so an invisible type can never move a visible number.
pub(crate) fn visible_types(graph: &DirGraph) -> impl Iterator<Item = (&str, usize)> + '_ {
    graph
        .type_indices
        .iter()
        .filter(|(nt, _)| !crate::graph::schema::is_system_label(nt))
        .map(|(nt, indices)| (nt, indices.len()))
}

/// The whole-graph node count minus the members of every system label.
/// Subtractive rather than a sum over [`visible_types`] so the number stays
/// byte-identical to `node_count()` on the overwhelmingly common graph that
/// carries no system-labelled node at all.
pub(crate) fn visible_node_count(graph: &DirGraph) -> usize {
    let hidden: usize = graph
        .type_indices
        .iter()
        .filter(|(nt, _)| crate::graph::schema::is_system_label(nt))
        .map(|(_, indices)| indices.len())
        .sum();
    graph.graph.node_count().saturating_sub(hidden)
}

/// Classify graph scale by core type count (excluding supporting types).
pub fn graph_scale(graph: &DirGraph) -> GraphScale {
    let core_count = visible_types(graph)
        .filter(|(nt, _)| !graph.parent_types.contains_key(*nt))
        .count();
    match core_count {
        0..=15 => GraphScale::Small,
        16..=200 => GraphScale::Medium,
        201..=5000 => GraphScale::Large,
        _ => GraphScale::Extreme,
    }
}

/// Which surface is asking for a description, so its hints can name a callable
/// the reader can actually invoke.
///
/// The rendered document is full of "call X for more" hints, and one spelling
/// cannot serve all three: `graph_overview` is an MCP tool name, not a
/// `KnowledgeGraph` method, and the CLI takes flags rather than keyword
/// arguments. See [`DescribeSurface::call`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DescribeSurface {
    /// Python `KnowledgeGraph.describe(...)`.
    Python,
    /// The `kglite describe` subcommand.
    Cli,
    /// The MCP `graph_overview` tool.
    Mcp,
}

impl DescribeSurface {
    /// Render one "call this for more" hint in this surface's own spelling.
    ///
    /// `kwargs` is the keyword-argument form the Python method and the MCP
    /// tool share (`types=['T']`); `flags` is the CLI's (`--types T`), which
    /// is a different shape, not a different name. Both spellings are supplied
    /// at the hint site so neither can be grown without the other.
    ///
    /// The result lands inside an XML attribute, so no spelling may contain
    /// `<`, `>` or a double quote — pinned by
    /// `describe_tests::surface_hint_tests::no_surface_spelling_breaks_the_xml`.
    pub fn call(self, kwargs: &str, flags: &str) -> String {
        match self {
            DescribeSurface::Python => format!("describe({kwargs})"),
            DescribeSurface::Mcp => format!("graph_overview({kwargs})"),
            DescribeSurface::Cli => format!("kglite describe GRAPH {flags}"),
        }
    }
}

/// Level of Cypher documentation requested via `describe(cypher=...)`.
pub enum CypherDetail {
    /// No Cypher docs (default).
    Off,
    /// Tier 2: compact reference for the major supported Cypher surface.
    Overview,
    /// Tier 3: detailed docs with params and examples for specific topics.
    Topics(Vec<String>),
}

/// Level of fluent API documentation requested via `describe(fluent=...)`.
pub enum FluentDetail {
    /// No fluent docs (default).
    Off,
    /// Compact reference: all methods grouped by area with 1-line descriptions.
    Overview,
    /// Detailed docs with params and examples for specific topics.
    Topics(Vec<String>),
}

/// Level of connection documentation requested via `describe(connections=...)`.
pub enum ConnectionDetail {
    /// No standalone connection docs (default — connections shown in inventory).
    Off,
    /// Overview: all connection types with count, endpoints, property names.
    Overview,
    /// Deep-dive: specific connection types with per-pair counts, property stats, samples.
    Topics(Vec<String>),
}