forjar 1.25.1

//! FJ-110: Language Server Protocol for forjar YAML.
//!
//! Lightweight LSP server over stdio using JSON-RPC 2.0.
//! Provides: autocompletion, hover docs, diagnostics (validation),
//! go-to-definition for includes/data sources.
//! No external LSP library — raw JSON-RPC protocol.

use std::collections::HashMap;
use std::io::{self, BufRead, Write};

/// LSP server state.
#[derive(Debug)]
pub struct LspServer {
    /// Whether the client has sent `initialize`.
    pub initialized: bool,
    /// Open document URIs mapped to their content.
    pub documents: HashMap<String, String>,
    /// Workspace root URI.
    pub root_uri: Option<String>,
    /// Whether a shutdown was requested.
    pub shutdown_requested: bool,
}

/// LSP diagnostic severity.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum DiagnosticSeverity {
    /// Error severity.
    Error = 1,
    /// Warning severity.
    Warning = 2,
    /// Informational severity.
    Information = 3,
    /// Hint severity.
    Hint = 4,
}

/// LSP diagnostic.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct Diagnostic {
    /// Start line (0-based).
    pub line: u32,
    /// Start character offset.
    pub character: u32,
    /// End line (0-based).
    pub end_line: u32,
    /// End character offset.
    pub end_character: u32,
    /// Diagnostic severity level.
    pub severity: DiagnosticSeverity,
    /// Diagnostic message.
    pub message: String,
    /// Source identifier (e.g., "forjar-lsp").
    pub source: String,
}

/// LSP completion item.
///
/// GH-212 (#208): `rename_all = "camelCase"` is load-bearing, not cosmetic.
/// The wire name of this field is `insertText`; serialised as the Rust
/// `insert_text` every LSP client ignores it and inserts the bare `label`, so
/// the deliberately chosen `"type: "` (trailing colon and space) was silently
/// discarded and users got `type`. Every other struct this server puts on the
/// wire is already camelCase — this one was the outlier.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CompletionItem {
    /// Display label.
    pub label: String,
    /// Detail description.
    pub detail: String,
    /// Text to insert on accept.
    pub insert_text: String,
    /// Completion kind (1=Text, 6=Variable, 14=Keyword, 15=Snippet).
    pub kind: u32,
}

/// Known forjar YAML top-level keys.
const TOP_LEVEL_KEYS: &[(&str, &str)] = &[
    ("machines", "Machine definitions (name, host, transport)"),
    ("resources", "Resource definitions (package, file, service)"),
    ("data", "Data sources (file, forjar-state, environment)"),
    ("tags", "Tag assignments for resources"),
    ("policy", "Policy configuration (convergence, security)"),
    ("includes", "Include other forjar YAML files"),
    ("template", "Template parameters for reusable configs"),
];

/// Known resource types.
const RESOURCE_TYPES: &[(&str, &str)] = &[
    ("package", "System package (apt, yum, brew, cargo)"),
    ("file", "File resource (content, template, permissions)"),
    ("service", "System service (systemd, launchd)"),
    ("mount", "Filesystem mount point"),
    ("directory", "Directory with ownership/permissions"),
    ("command", "Arbitrary command execution"),
    ("git_repo", "Git repository clone/checkout"),
    ("cron", "Cron job definition"),
    ("user", "System user account"),
    ("group", "System group"),
    ("gpu_driver", "GPU driver installation (NVIDIA/ROCm)"),
];

/// Known resource fields.
const RESOURCE_FIELDS: &[(&str, &str)] = &[
    ("name", "Resource identifier (unique within config)"),
    ("type", "Resource type (package, file, service, etc.)"),
    (
        "ensure",
        "Desired state: present|absent|latest|running|stopped",
    ),
    ("provider", "Package provider: apt, yum, brew, cargo, pip"),
    ("content", "File content (inline string)"),
    ("source", "File source path or URL"),
    ("mode", "File permissions (octal, e.g., '0644')"),
    ("owner", "File/directory owner"),
    ("group", "File/directory group"),
    ("depends_on", "List of resource dependencies"),
    ("machine", "Target machine name"),
    ("tags", "Resource tags for filtering"),
    ("on_success", "Notification on successful convergence"),
    ("on_failure", "Notification on failure"),
    ("on_drift", "Notification when drift detected"),
];

impl Default for LspServer {
    fn default() -> Self {
        Self::new()
    }
}

impl LspServer {
    /// Create a new LSP server instance.
    pub fn new() -> Self {
        LspServer {
            initialized: false,
            documents: HashMap::new(),
            root_uri: None,
            shutdown_requested: false,
        }
    }

    /// Handle a JSON-RPC request and return optional response.
    pub fn handle_message(&mut self, msg: &serde_json::Value) -> Option<serde_json::Value> {
        let method = msg.get("method")?.as_str()?;
        let id = msg.get("id");

        match method {
            "initialize" => Some(make_response(id, self.on_initialize(msg))),
            "initialized" => None, // notification, no response
            "shutdown" => Some(make_response(id, self.on_shutdown())),
            "exit" => std::process::exit(self.exit_code()),
            "textDocument/didOpen" => {
                self.handle_did_open(msg);
                None
            }
            "textDocument/didChange" => {
                self.handle_did_change(msg);
                None
            }
            "textDocument/completion" => Some(make_response(id, self.completion_result(msg))),
            "textDocument/hover" => Some(make_response(id, self.handle_hover(msg))),
            // GH-210 (#208): pull diagnostics — see `diagnostic_report`.
            "textDocument/diagnostic" => Some(make_response(id, self.diagnostic_report(msg))),
            _ => unknown_method_response(id),
        }
    }

    /// Accept the `initialize` handshake: record the client's workspace root
    /// (when it sent one) and answer with this server's capabilities.
    fn on_initialize(&mut self, msg: &serde_json::Value) -> serde_json::Value {
        self.initialized = true;
        if let Some(root) = msg.pointer("/params/rootUri") {
            self.root_uri = root.as_str().map(String::from);
        }
        initialize_result()
    }

    /// Record that the client asked to shut down — the flag `exit_code` reads —
    /// and answer with the null result the LSP `shutdown` request expects.
    fn on_shutdown(&mut self) -> serde_json::Value {
        self.shutdown_requested = true;
        serde_json::Value::Null
    }

    /// Process exit status for the `exit` notification: 0 when a `shutdown`
    /// request preceded it, 1 when the client exits without one.
    fn exit_code(&self) -> i32 {
        if self.shutdown_requested {
            0
        } else {
            1
        }
    }

    /// The completion list as a JSON-RPC result. Encoding a `Vec` of plain
    /// structs cannot realistically fail; if it did, the client sees `null`.
    fn completion_result(&self, msg: &serde_json::Value) -> serde_json::Value {
        let items = self.handle_completion(msg);
        serde_json::to_value(items).unwrap_or_default()
    }

    /// Serve a pull-diagnostics report for the document a request names.
    ///
    /// GH-210 (#208): `initialize` advertises `diagnosticProvider`, which per
    /// the LSP spec DECLARES that `textDocument/diagnostic` is handled. It was
    /// not: clients that honour the capability (recent VS Code and nvim prefer
    /// pull diagnostics when advertised) fell through to the default arm and
    /// got -32601 "Method not found" instead of diagnostics. This builds a full
    /// DocumentDiagnosticReport from exactly the same validation that feeds
    /// push diagnostics, so the two mechanisms cannot disagree.
    fn diagnostic_report(&self, msg: &serde_json::Value) -> serde_json::Value {
        let diags = self.validate_document(document_uri(msg));
        super::lsp_publish::full_report(&diags)
    }

    fn handle_did_open(&mut self, msg: &serde_json::Value) {
        if let (Some(uri), Some(text)) = (
            msg.pointer("/params/textDocument/uri")
                .and_then(|v| v.as_str()),
            msg.pointer("/params/textDocument/text")
                .and_then(|v| v.as_str()),
        ) {
            self.documents.insert(uri.to_string(), text.to_string());
        }
    }

    fn handle_did_change(&mut self, msg: &serde_json::Value) {
        if let (Some(uri), Some(changes)) = (
            msg.pointer("/params/textDocument/uri")
                .and_then(|v| v.as_str()),
            msg.pointer("/params/contentChanges")
                .and_then(|v| v.as_array()),
        ) {
            // Full document sync — take last change
            if let Some(text) = changes
                .last()
                .and_then(|c| c.get("text"))
                .and_then(|t| t.as_str())
            {
                self.documents.insert(uri.to_string(), text.to_string());
            }
        }
    }

    fn handle_completion(&self, msg: &serde_json::Value) -> Vec<CompletionItem> {
        let uri = document_uri(msg);
        let line = msg
            .pointer("/params/position/line")
            .and_then(|v| v.as_u64())
            .unwrap_or(0) as usize;

        let doc = match self.documents.get(uri) {
            Some(d) => d,
            None => return Vec::new(),
        };
        let current_line = doc.lines().nth(line).unwrap_or("");
        let indent = current_line.len() - current_line.trim_start().len();
        completion_items(indent, current_line.trim())
    }

    fn handle_hover(&self, msg: &serde_json::Value) -> serde_json::Value {
        let uri = document_uri(msg);
        let line = msg
            .pointer("/params/position/line")
            .and_then(|v| v.as_u64())
            .unwrap_or(0) as usize;

        let doc = match self.documents.get(uri) {
            Some(d) => d,
            None => return serde_json::Value::Null,
        };
        let current_line = doc.lines().nth(line).unwrap_or("");
        hover_info(current_line.trim())
    }

    /// Validate a document and return diagnostics.
    pub fn validate_document(&self, uri: &str) -> Vec<Diagnostic> {
        let doc = match self.documents.get(uri) {
            Some(d) => d,
            None => return Vec::new(),
        };
        validate_yaml(doc)
    }
}

/// The document URI a `textDocument/*` request names, or `""` when the request
/// omits it.
///
/// Exists so the three request handlers that need it share one spelling of the
/// pointer; `""` is never an open document, so a malformed request reads as
/// "no such document" exactly as it did inline.
fn document_uri(msg: &serde_json::Value) -> &str {
    msg.pointer("/params/textDocument/uri")
        .and_then(|v| v.as_str())
        .unwrap_or("")
}

/// Reply to a method this server does not implement.
///
/// A *request* (it carries an `id`) gets JSON-RPC error -32601; a notification
/// carries no `id` and must go unanswered.
fn unknown_method_response(id: Option<&serde_json::Value>) -> Option<serde_json::Value> {
    if id.is_some() {
        Some(make_error_response(id, -32601, "Method not found"))
    } else {
        None // unknown notification
    }
}

/// Generate completion items based on context.
pub(crate) fn completion_items(indent: usize, line_prefix: &str) -> Vec<CompletionItem> {
    let mut items = Vec::new();
    if indent == 0 && (line_prefix.is_empty() || !line_prefix.contains(':')) {
        // Top-level keys
        for (key, desc) in TOP_LEVEL_KEYS {
            items.push(CompletionItem {
                label: key.to_string(),
                detail: desc.to_string(),
                insert_text: format!("{key}:"),
                kind: 14, // Keyword
            });
        }
    } else if line_prefix.starts_with("type:") || line_prefix.starts_with("- type:") {
        // Resource types
        for (rtype, desc) in RESOURCE_TYPES {
            items.push(CompletionItem {
                label: rtype.to_string(),
                detail: desc.to_string(),
                insert_text: rtype.to_string(),
                kind: 6, // Variable
            });
        }
    } else if indent >= 2 {
        // Resource fields
        for (field, desc) in RESOURCE_FIELDS {
            items.push(CompletionItem {
                label: field.to_string(),
                detail: desc.to_string(),
                insert_text: format!("{field}: "),
                kind: 6, // Variable
            });
        }
    }
    items
}

/// Generate hover info for a line.
pub(super) fn hover_info(line: &str) -> serde_json::Value {
    let key = line
        .split(':')
        .next()
        .unwrap_or("")
        .trim()
        .trim_start_matches("- ");
    let desc = TOP_LEVEL_KEYS
        .iter()
        .chain(RESOURCE_FIELDS.iter())
        .chain(RESOURCE_TYPES.iter())
        .find(|(k, _)| *k == key)
        .map(|(_, d)| *d);

    match desc {
        Some(d) => serde_json::json!({
            "contents": { "kind": "markdown", "value": format!("**{key}**: {d}") }
        }),
        None => serde_json::Value::Null,
    }
}

// GH-215: validation lives in `lsp_validate` (file-size ceiling); re-exported
// here so callers and tests keep using `lsp::validate_yaml` / `lsp::make_diag`.
#[cfg(test)]
pub(super) use super::lsp_validate::make_diag;
pub use super::lsp_validate::validate_yaml;

/// Build an LSP initialize result.
pub(super) fn initialize_result() -> serde_json::Value {
    serde_json::json!({
        "capabilities": {
            "textDocumentSync": 1,
            "completionProvider": { "triggerCharacters": [":", " ", "-"] },
            "hoverProvider": true,
            "diagnosticProvider": { "interFileDependencies": false, "workspaceDiagnostics": false }
        },
        "serverInfo": { "name": "forjar-lsp", "version": env!("CARGO_PKG_VERSION") }
    })
}

pub(super) fn make_response(
    id: Option<&serde_json::Value>,
    result: serde_json::Value,
) -> serde_json::Value {
    serde_json::json!({
        "jsonrpc": "2.0",
        "id": id.cloned().unwrap_or(serde_json::Value::Null),
        "result": result
    })
}

pub(super) fn make_error_response(
    id: Option<&serde_json::Value>,
    code: i32,
    msg: &str,
) -> serde_json::Value {
    serde_json::json!({
        "jsonrpc": "2.0",
        "id": id.cloned().unwrap_or(serde_json::Value::Null),
        "error": { "code": code, "message": msg }
    })
}

/// Write an LSP message (Content-Length header + JSON body).
pub fn write_message<W: Write>(writer: &mut W, msg: &serde_json::Value) -> io::Result<()> {
    let body = serde_json::to_string(msg).map_err(io::Error::other)?;
    write!(writer, "Content-Length: {}\r\n\r\n{}", body.len(), body)?;
    writer.flush()
}

/// Read one LSP message from stdin.
pub fn read_message<R: BufRead>(reader: &mut R) -> io::Result<serde_json::Value> {
    let mut header = String::new();
    let mut content_length: usize = 0;

    loop {
        header.clear();
        reader.read_line(&mut header)?;
        let trimmed = header.trim();
        if trimmed.is_empty() {
            break;
        }
        if let Some(len_str) = trimmed.strip_prefix("Content-Length: ") {
            content_length = len_str
                .parse()
                .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))?;
        }
    }

    if content_length == 0 {
        return Err(io::Error::new(
            io::ErrorKind::UnexpectedEof,
            "no content length",
        ));
    }

    let mut body = vec![0u8; content_length];
    reader.read_exact(&mut body)?;
    serde_json::from_slice(&body).map_err(|e| io::Error::new(io::ErrorKind::InvalidData, e))
}

/// Entry point: run the LSP server on stdio.
pub fn cmd_lsp() -> Result<(), String> {
    let stdin = io::stdin();
    let stdout = io::stdout();
    let mut reader = stdin.lock();
    let mut writer = stdout.lock();
    let mut server = LspServer::new();

    loop {
        let msg = read_message(&mut reader).map_err(|e| e.to_string())?;
        if let Some(resp) = server.handle_message(&msg) {
            write_message(&mut writer, &resp).map_err(|e| e.to_string())?;
        }
        // Publish diagnostics after document changes
        if let Some(method) = msg.get("method").and_then(|m| m.as_str()) {
            if method == "textDocument/didOpen" || method == "textDocument/didChange" {
                if let Some(uri) = msg
                    .pointer("/params/textDocument/uri")
                    .and_then(|v| v.as_str())
                {
                    let diags = server.validate_document(uri);
                    let notification = super::lsp_publish::publish_diagnostics(uri, &diags);
                    write_message(&mut writer, &notification).map_err(|e| e.to_string())?;
                }
            }
        }
    }
}

// Re-export for test modules that use `super::lsp::*`
#[cfg(test)]
pub(super) use super::lsp_publish::publish_diagnostics;