atomwrite 0.1.37

// SPDX-License-Identifier: MIT OR Apache-2.0

//! v14 Tier 3 subcommand (v0.1.12): `outline` — extract the high-level
//! structure of a source file (functions, classes, structs, enums,
//! traits, modules, top-level consts) as NDJSON. Uses
//! `tree-sitter-language-pack`.
//!
//! Workload: mixed I/O-bound + CPU-bound (file read + tree-sitter outline walk).
//! Parallelism: single-file; no multi-file fan-out in this subcommand.
//!
//! ## Cause and Effect
//!
//! - **Cause**: `read` returns raw text. LLM agents spend tokens reading
//!   500 lines only to learn that 12 of them are signatures.
//! - **Effect**: Wasted context, high latency, and scope hallucinations
//!   (assuming function X exists when X lives in module Y).
//! - **Solution**: Parse with tree-sitter, walk top-level structural node
//!   kinds, and emit each as `outline_item` NDJSON with `kind`, `name`,
//!   `signature`, and `start_line`.
//! - **Benefit**: Compact, precise, navigable context (10 items ≈ 2 KB vs
//!   50 KB of full source).

use std::io::Write;
use std::time::Instant;

use anyhow::{Context, Result};
use serde::Serialize;

use crate::cli::{GlobalArgs, OutlineArgs};
use crate::output::NdjsonWriter;

/// One structural outline item (NDJSON `outline_item`).
#[derive(Debug, Clone, Serialize)]
pub struct OutlineItem {
    /// Event type discriminator (`outline_item`).
    pub r#type: &'static str,
    /// Source file path.
    pub path: String,
    /// Detected/selected language id.
    pub language: String,
    /// Structural node kind (function, class, …).
    pub kind: String,
    /// Extracted symbol name.
    pub name: String,
    /// Compact signature snippet.
    pub signature: String,
    /// 1-based start line.
    pub start_line: usize,
    /// 1-based end line.
    pub end_line: usize,
    /// Optional byte offset start (`--positions`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub start_byte: Option<usize>,
    /// Optional byte offset end (`--positions`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub end_byte: Option<usize>,
    /// Optional start column (`--positions`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub start_column: Option<usize>,
    /// Optional end column (`--positions`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub end_column: Option<usize>,
    /// Present and true when `signature` was cut.
    ///
    /// The cut happens at `OUTLINE_SIGNATURE_MAX_BYTES` or at the first line,
    /// so a reader that saw a signature ending in `{` knows the body was not
    /// part of it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub signature_truncated: Option<bool>,
}

/// Terminal event of `outline`: item count for one file.
#[derive(Debug, Serialize, schemars::JsonSchema)]
pub(crate) struct OutlineSummary {
    r#type: &'static str,
    path: String,
    language: String,
    items: usize,
    elapsed_ms: u64,
    /// Items that were emitted with a cut `signature` field.
    ///
    /// The item itself is in the stream: only `signature` was shortened, at
    /// `OUTLINE_SIGNATURE_MAX_BYTES` or at the first line. This never means
    /// an item was left out.
    #[serde(skip_serializing_if = "Option::is_none")]
    items_truncated: Option<u64>,
    /// Items the `--limit` budget kept out of the stream.
    ///
    /// Distinct from `items_truncated`, which counts cut signatures, not
    /// missing items.
    #[serde(skip_serializing_if = "Option::is_none")]
    items_omitted: Option<u64>,
}

const STRUCTURAL_NODE_KINDS: &[&str] = &[
    "function_item",
    "function_definition",
    "function_declaration",
    "method_declaration",
    "function",
    "generator_function_declaration",
    "class_item",
    "class_definition",
    "class_declaration",
    "class",
    "struct_item",
    "struct_declaration",
    "struct_type",
    "enum_item",
    "enum_declaration",
    "trait_item",
    "interface_declaration",
    "impl_item",
    "module",
    "mod_item",
    "const_item",
    "static_item",
    "type_item",
    "type_alias",
    "macro_invocation",
    "namespace_declaration",
    "lambda",
    "arrow_function",
];

/// Execute the `outline` subcommand.
///
/// Reads the source file, parses it via `tree-sitter-language-pack`,
/// walks the tree looking for structural node kinds (functions,
/// classes, structs, etc.), and emits each as an `outline_item`
/// NDJSON line. After the tree is exhausted, a final
/// `outline_summary` line is emitted with the total count.
///
/// # Errors
///
/// Returns `AtomwriteError::NotFound` when the target file does not exist.
/// Returns `AtomwriteError::WorkspaceJail` when the path escapes the workspace.
/// Returns `AtomwriteError::FileTooLarge` when the file exceeds the effective max filesize.
/// Returns `AtomwriteError::InvalidInput` when `--language` names an unsupported grammar or the
/// language cannot be detected from the path and content.
/// Returns an error when no tree-sitter parser is available for the language or the parser
/// returns no tree.
/// Returns `AtomwriteError::Io` when the file cannot be read.
/// Returns `AtomwriteError::BrokenPipe` when the consumer closes the NDJSON stream.
#[tracing::instrument(skip_all, fields(command = "outline"))]
pub fn cmd_outline(
    args: &OutlineArgs,
    global: &GlobalArgs,
    writer: &mut NdjsonWriter<impl Write>,
) -> Result<()> {
    let start = Instant::now();
    let workspace = global.resolve_workspace()?;
    let validated = crate::path_safety::validate_path(&args.path, &workspace)?;
    if !validated.exists() {
        return Err(crate::error::AtomwriteError::NotFound { path: validated }.into());
    }
    let content = crate::file_io::read_file_bytes(&validated, global.effective_max_filesize())?;

    let lang_name = crate::commands::query::resolve_language_name(
        args.language.as_deref(),
        &validated,
        &content,
    )?;
    let kind_filter: Option<Vec<String>> = if args.kinds.is_empty() {
        None
    } else {
        Some(args.kinds.iter().map(|s| s.to_lowercase()).collect())
    };

    let mut parser = crate::grammar::parser_for(&lang_name)?;
    let tree = parser
        .parse(std::str::from_utf8(&content).unwrap_or(""))
        .or_else(|| parser.parse_bytes(&content))
        .with_context(|| format!("parser returned no tree for {lang_name}"))?;
    let root = tree.root_node();

    let mut collected = Vec::new();
    walk_outline_collect(
        &root,
        &content,
        &validated,
        &lang_name,
        &kind_filter,
        args.positions,
        &mut collected,
    );
    let items_truncated = collected
        .iter()
        .filter(|i| i.signature_truncated == Some(true))
        .count() as u64;
    let mut items: usize = 0;
    let mut omitted: u64 = 0;
    for item in collected {
        // The record budget is spent: this item is work the consumer may not
        // read, so the count says how many the stream left out.
        if crate::output::remaining_budget() == Some(0) {
            omitted = omitted.saturating_add(1);
            continue;
        }
        writer.write_event(&item)?;
        items += 1;
    }

    let elapsed_ms = start.elapsed().as_millis() as u64;
    writer.write_terminal(&OutlineSummary {
        r#type: "outline_summary",
        path: validated.display().to_string(),
        language: lang_name,
        items,
        elapsed_ms,
        items_truncated: (items_truncated > 0).then_some(items_truncated),
        items_omitted: (omitted > 0).then_some(omitted),
    })?;
    Ok(())
}

/// Collect structural outline items for one file (no I/O writer — rayon-safe).
///
/// Parse failures return an empty vec so budgeted callers can skip quietly.
pub fn collect_outline_for_path(
    path: &std::path::Path,
    content: &[u8],
    language: Option<&str>,
) -> Vec<OutlineItem> {
    collect_outline_for_path_status(path, content, language).0
}

/// Collect outline items and say whether the file was parsed at all.
///
/// `false` means no grammar was resolved or the parser returned no tree, and
/// the empty vec is a hole instead of a file without symbols.
pub fn collect_outline_for_path_status(
    path: &std::path::Path,
    content: &[u8],
    language: Option<&str>,
) -> (Vec<OutlineItem>, bool) {
    let lang_name = match crate::commands::query::resolve_language_name(language, path, content) {
        Ok(l) => l,
        Err(_) => return (Vec::new(), false),
    };
    let mut parser = match crate::grammar::parser_for(&lang_name) {
        Ok(p) => p,
        Err(_) => return (Vec::new(), false),
    };
    let tree = match parser
        .parse(std::str::from_utf8(content).unwrap_or(""))
        .or_else(|| parser.parse_bytes(content))
    {
        Some(t) => t,
        None => return (Vec::new(), false),
    };
    let root = tree.root_node();
    let mut out = Vec::new();
    walk_outline_collect(&root, content, path, &lang_name, &None, false, &mut out);
    (out, true)
}

/// Emit structural outline items for one file (used by `outline` and `sparse outline`).
///
/// Returns the number of items emitted. Parse failures return `Ok(0)` so callers
/// can skip unsupported/binary files under a budget.
///
/// # Errors
///
/// Returns `AtomwriteError::BrokenPipe` when the consumer closes the NDJSON stream.
/// Returns a serialization error when an outline item cannot be encoded as JSON.
pub fn emit_outline_for_path(
    path: &std::path::Path,
    content: &[u8],
    language: Option<&str>,
    writer: &mut NdjsonWriter<impl Write>,
) -> Result<usize> {
    let items = collect_outline_for_path(path, content, language);
    let n = items.len();
    for item in items {
        writer.write_event(&item)?;
    }
    Ok(n)
}

#[allow(clippy::too_many_arguments)]
fn walk_outline_collect(
    root: &tree_sitter_language_pack::Node,
    source: &[u8],
    path: &std::path::Path,
    lang_name: &str,
    kind_filter: &Option<Vec<String>>,
    show_positions: bool,
    out: &mut Vec<OutlineItem>,
) {
    let mut stack: Vec<tree_sitter_language_pack::Node> = vec![root.clone()];
    while let Some(node) = stack.pop() {
        let kind = node.kind();
        if STRUCTURAL_NODE_KINDS.contains(&kind.as_str()) {
            let lc_kind = kind.to_lowercase();
            let matches_filter = match kind_filter {
                Some(f) => f.iter().any(|k| k == &lc_kind || k == &kind),
                None => true,
            };
            if matches_filter {
                let name = extract_name(&node, source);
                let (signature, signature_truncated) = extract_signature(&node, source);
                let start = node.start_position();
                let end = node.end_position();
                out.push(OutlineItem {
                    r#type: "outline_item",
                    path: path.display().to_string(),
                    language: lang_name.to_string(),
                    kind: kind.to_string(),
                    name,
                    signature,
                    start_line: start.row + 1,
                    end_line: end.row + 1,
                    start_byte: if show_positions {
                        Some(node.start_byte())
                    } else {
                        None
                    },
                    end_byte: if show_positions {
                        Some(node.end_byte())
                    } else {
                        None
                    },
                    start_column: if show_positions {
                        Some(start.column)
                    } else {
                        None
                    },
                    end_column: if show_positions {
                        Some(end.column)
                    } else {
                        None
                    },
                    signature_truncated: signature_truncated.then_some(true),
                });
            }
        }
        let count = node.child_count() as u32;
        for i in (0..count).rev() {
            if let Some(child) = node.child(i) {
                stack.push(child);
            }
        }
    }
}

fn extract_name(node: &tree_sitter_language_pack::Node, source: &[u8]) -> String {
    for kind in ["name", "identifier", "type_identifier", "constant"] {
        if let Some(child) = node.child_by_field_name(kind) {
            return child_text(source, child);
        }
    }
    let mut cursor = node.walk();
    if cursor.goto_first_child() {
        loop {
            let c = cursor.node();
            if c.is_named() {
                let text = child_text(source, c);
                if !text.is_empty() {
                    return text;
                }
            }
            if !cursor.goto_next_sibling() {
                break;
            }
        }
    }
    "<anonymous>".to_string()
}

/// Extract the compact signature, saying whether it was cut.
///
/// Two cuts are possible and both count: the per-item byte ceiling, and the
/// first line of a node that spans many lines.
fn extract_signature(node: &tree_sitter_language_pack::Node, source: &[u8]) -> (String, bool) {
    let start = node.start_byte();
    let node_end = node.end_byte();
    let end = node_end.min(start + crate::constants::OUTLINE_SIGNATURE_MAX_BYTES);
    let raw = source.get(start..end).unwrap_or(&[]);
    let s = String::from_utf8_lossy(raw);
    let line = s.lines().next().unwrap_or("");
    let cut = node_end > end || s.len() > line.len();
    let collapsed: String = line
        .chars()
        .filter(|c| !c.is_control() || *c == '\t')
        .collect();
    let trimmed = collapsed.trim();
    if trimmed.is_empty() {
        ("<empty>".to_owned(), cut)
    } else {
        (trimmed.to_string(), cut)
    }
}

fn child_text(source: &[u8], node: tree_sitter_language_pack::Node) -> String {
    let start = node.start_byte();
    let end = node.end_byte().min(source.len());
    String::from_utf8_lossy(source.get(start..end).unwrap_or(&[])).to_string()
}

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

    #[test]
    fn structural_node_kinds_includes_common_ones() {
        assert!(STRUCTURAL_NODE_KINDS.contains(&"function_item"));
        assert!(STRUCTURAL_NODE_KINDS.contains(&"struct_item"));
        assert!(STRUCTURAL_NODE_KINDS.contains(&"class_definition"));
        assert!(STRUCTURAL_NODE_KINDS.contains(&"trait_item"));
    }

    #[test]
    fn kind_filter_lowercases_input() {
        // Filter "function_item" should match an exact "function_item" node.
        let f = Some(vec!["function_item".to_string()]);
        let s = f.as_ref().unwrap();
        let any_match = s.iter().any(|k| k == "function_item");
        assert!(any_match);
    }
}