readseek 0.7.6

// SPDX-License-Identifier: LGPL-2.1-or-later
// Copyright (c) 2026 Jarkko Sakkinen

use crate::engine::flags::GitFlags;
use crate::engine::lang::{LANGUAGE_SPECS, Language};
use crate::engine::output::ImageMode;
use crate::engine::target::{Target, TargetAddress};
use crate::engine::vision::VisionProfile;
use anyhow::{Context, Result, bail};
use argh::FromArgs;
use std::path::PathBuf;

pub(crate) mod run;

/// readseek
#[derive(Debug, FromArgs)]
#[argh(help_triggers("-h", "--help"))]
pub(crate) struct Cli {
    /// print version and exit
    #[argh(switch, short = 'V')]
    pub(crate) version: bool,

    /// write output to file instead of stdout
    #[argh(option, long = "output")]
    pub(crate) output: Option<PathBuf>,

    /// use the given .readseek directory instead of discovering one
    #[argh(option, long = "readseek-dir")]
    pub(crate) readseek_dir: Option<PathBuf>,

    /// command to run
    #[argh(subcommand)]
    pub(crate) command: Option<Command>,
}

#[derive(Debug, FromArgs)]
#[argh(subcommand)]
pub(crate) enum Command {
    Detect(DetectCommand),
    Read(ReadCommand),
    View(ViewCommand),
    Map(MapCommand),
    Check(CheckCommand),
    Symbol(SymbolCommand),
    Identify(IdentifyCommand),
    Def(DefCommand),
    Refs(RefsCommand),
    Rename(RenameCommand),
    Search(SearchCommand),
    Init(InitCommand),
}

/// detect the file type
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "detect")]
#[argh(help_triggers("-h", "--help"))]
pub(crate) struct DetectCommand {
    /// takes <file> or stdin:<path>
    #[argh(positional)]
    pub(crate) target: Option<String>,
}

/// read and hash from a line range
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "read")]
#[argh(help_triggers("-h", "--help"))]
pub(crate) struct ReadCommand {
    /// takes <file>, <file>:<line>, <file>:<hash>, stdin:<path>[:<line>|<hash>], or stdin:
    #[argh(positional)]
    pub(crate) target: Option<String>,

    /// last line to include
    #[argh(option)]
    pub(crate) end: Option<usize>,

    /// maximum number of lines to include
    #[argh(option)]
    pub(crate) limit: Option<usize>,

    /// one-based PDF page to read
    #[argh(option)]
    pub(crate) page: Option<usize>,

    /// language override
    #[argh(option, from_str_fn(parse_language))]
    pub(crate) language: Option<Language>,

    /// image mode: none (default), all, caption, objects, or ocr
    #[argh(option, from_str_fn(parse_image_mode))]
    pub(crate) image: Option<ImageMode>,

    /// vision inference profile: fast, balanced (default), or accurate
    #[argh(option, from_str_fn(parse_vision_profile))]
    pub(crate) vision_profile: Option<VisionProfile>,

    /// emit vision inference diagnostics as JSON on stderr
    #[argh(switch)]
    pub(crate) vision_diagnostics: bool,

    /// benchmark vision inference for this many measured iterations after warmup
    #[argh(option)]
    pub(crate) vision_benchmark: Option<usize>,
}

/// view an indexed document
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "view")]
#[argh(help_triggers("-h", "--help"))]
pub(crate) struct ViewCommand {
    /// document file to view
    #[argh(positional)]
    pub(crate) target: Option<String>,

    /// output format: plain (default) or json
    #[argh(
        option,
        long = "format",
        default = "crate::engine::output::Format::Plain"
    )]
    pub(crate) format: crate::engine::output::Format,

    /// node ID to use as the view root
    #[argh(option)]
    pub(crate) node: Option<String>,

    /// one-based source page to view
    #[argh(option)]
    pub(crate) page: Option<usize>,

    /// node kind to include
    #[argh(option)]
    pub(crate) kind: Option<crate::engine::document::NodeKind>,

    /// maximum node depth to include
    #[argh(option)]
    pub(crate) depth: Option<usize>,

    /// show the document outline only
    #[argh(switch)]
    pub(crate) outline: bool,
}

/// map a file to symbols
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "map")]
#[argh(help_triggers("-h", "--help"))]
pub(crate) struct MapCommand {
    /// takes <file> or stdin:<path>
    #[argh(positional)]
    pub(crate) target: Option<String>,

    /// language override
    #[argh(option, from_str_fn(parse_language))]
    pub(crate) language: Option<Language>,
}

/// report parse diagnostics for a file
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "check")]
#[argh(help_triggers("-h", "--help"))]
pub(crate) struct CheckCommand {
    /// takes <file> or stdin:<path>
    #[argh(positional)]
    pub(crate) target: Option<String>,

    /// language override
    #[argh(option, from_str_fn(parse_language))]
    pub(crate) language: Option<Language>,
}

/// read the line range for a symbol
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "symbol")]
#[argh(help_triggers("-h", "--help"))]
pub(crate) struct SymbolCommand {
    /// takes <file>, <file>:<line>, <file>:<hash>, stdin:<path>[:<line>|<hash>], or stdin:
    #[argh(positional)]
    pub(crate) target: Option<String>,

    /// treat the target suffix as a symbol name
    #[argh(switch)]
    pub(crate) name: bool,

    /// language override
    #[argh(option, from_str_fn(parse_language))]
    pub(crate) language: Option<Language>,
}

/// identify the cursor token and enclosing symbol
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "identify")]
#[argh(help_triggers("-h", "--help"))]
pub(crate) struct IdentifyCommand {
    /// takes <file>, <file>:<line>, <file>:<hash>, stdin:<path>[:<line>|<hash>], or stdin:
    #[argh(positional)]
    pub(crate) target: Option<String>,

    /// one-based cursor byte column
    #[argh(option)]
    pub(crate) column: Option<usize>,

    /// language override
    #[argh(option, from_str_fn(parse_language))]
    pub(crate) language: Option<Language>,
}

/// find structural symbol definitions
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "def")]
#[argh(help_triggers("-h", "--help"))]
#[allow(clippy::struct_excessive_bools)]
pub(crate) struct DefCommand {
    /// file or directory to search
    #[argh(positional)]
    pub(crate) target: PathBuf,

    /// qualified symbol name or unqualified name
    #[argh(positional)]
    pub(crate) name: String,

    /// output format
    #[argh(
        option,
        long = "format",
        default = "crate::engine::output::Format::Json"
    )]
    pub(crate) format: crate::engine::output::Format,

    /// language override
    #[argh(option, from_str_fn(parse_language))]
    pub(crate) language: Option<Language>,

    /// search tracked/indexed files when searching a Git repository
    #[argh(switch, short = 'c')]
    pub(crate) cached: bool,

    /// search untracked files when searching a Git repository
    #[argh(switch, short = 'o')]
    pub(crate) others: bool,

    /// include ignored untracked files when searching a Git repository
    #[argh(switch, short = 'i')]
    pub(crate) ignored: bool,
}

/// find identifier references
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "refs")]
#[argh(help_triggers("-h", "--help"))]
#[allow(clippy::struct_excessive_bools)]
pub(crate) struct RefsCommand {
    /// file or directory to search
    #[argh(positional)]
    pub(crate) target: PathBuf,

    /// identifier to search for
    #[argh(positional)]
    pub(crate) name: String,

    /// output format
    #[argh(
        option,
        long = "format",
        default = "crate::engine::output::Format::Json"
    )]
    pub(crate) format: crate::engine::output::Format,

    /// restrict results to the binding under --line/--column (single file)
    #[argh(switch)]
    pub(crate) scope: bool,

    /// one-based cursor line, used with --scope
    #[argh(option)]
    pub(crate) line: Option<usize>,

    /// one-based cursor byte column, used with --scope
    #[argh(option)]
    pub(crate) column: Option<usize>,

    /// language override
    #[argh(option, from_str_fn(parse_language))]
    pub(crate) language: Option<Language>,

    /// search tracked/indexed files when searching a Git repository
    #[argh(switch, short = 'c')]
    pub(crate) cached: bool,

    /// search untracked files when searching a Git repository
    #[argh(switch, short = 'o')]
    pub(crate) others: bool,

    /// include ignored untracked files when searching a Git repository
    #[argh(switch, short = 'i')]
    pub(crate) ignored: bool,
}

/// plan a binding-accurate rename within a single file
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "rename")]
#[argh(help_triggers("-h", "--help"))]
#[allow(clippy::struct_excessive_bools)]
pub(crate) struct RenameCommand {
    /// file holding the binding under the cursor (a single regular file)
    #[argh(positional)]
    pub(crate) target: PathBuf,

    /// one-based cursor line of the binding to rename
    #[argh(option)]
    pub(crate) line: usize,

    /// one-based cursor byte column of the binding to rename
    #[argh(option)]
    pub(crate) column: Option<usize>,

    /// new name for the binding
    #[argh(option, long = "to")]
    pub(crate) to: String,

    /// expand the rename across this directory or repository (name-based
    /// outside the cursor file); omit for a single-file rename
    #[argh(option)]
    pub(crate) workspace: Option<PathBuf>,

    /// write the planned edits to the file after verifying line hashes
    #[argh(switch)]
    pub(crate) apply: bool,

    /// require the apply plan to match this dry-run plan hash
    #[argh(option)]
    pub(crate) plan_hash: Option<String>,

    /// language override
    #[argh(option, from_str_fn(parse_language))]
    pub(crate) language: Option<Language>,

    /// search tracked/indexed files when expanding across a Git repository
    #[argh(switch, short = 'c')]
    pub(crate) cached: bool,

    /// search untracked files when expanding across a Git repository
    #[argh(switch, short = 'o')]
    pub(crate) others: bool,

    /// include ignored untracked files when expanding across a Git repository
    #[argh(switch, short = 'i')]
    pub(crate) ignored: bool,
}

/// search files with an AST pattern
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "search")]
#[argh(help_triggers("-h", "--help"))]
#[allow(clippy::struct_excessive_bools)]
pub(crate) struct SearchCommand {
    /// file or directory to search
    #[argh(positional)]
    pub(crate) target: PathBuf,

    /// ast-grep-style pattern
    #[argh(positional)]
    pub(crate) pattern: String,

    /// language override
    #[argh(option, from_str_fn(parse_language))]
    pub(crate) language: Option<Language>,

    /// search tracked/indexed files when searching a Git repository
    #[argh(switch, short = 'c')]
    pub(crate) cached: bool,

    /// search untracked files when searching a Git repository
    #[argh(switch, short = 'o')]
    pub(crate) others: bool,

    /// include ignored untracked files when searching a Git repository
    #[argh(switch, short = 'i')]
    pub(crate) ignored: bool,
}

/// initialize .readseek/ directory
#[derive(Debug, FromArgs)]
#[argh(subcommand, name = "init")]
#[argh(help_triggers("-h", "--help"))]
pub(crate) struct InitCommand {
    /// path to a directory (defaults to current directory)
    #[argh(positional)]
    pub(crate) path: Option<PathBuf>,
}

pub(crate) fn parse_language(value: &str) -> std::result::Result<Language, String> {
    if let Ok(language) = value.parse::<Language>() {
        return Ok(language);
    }

    let alias = value.to_ascii_lowercase().replace(['-', '_'], "");
    LANGUAGE_SPECS
        .iter()
        .find_map(|spec| {
            spec.aliases
                .contains(&alias.as_str())
                .then_some(spec.language)
        })
        .ok_or_else(|| format!("unknown language `{value}`"))
}

pub(crate) fn parse_image_mode(value: &str) -> std::result::Result<ImageMode, String> {
    match value {
        "none" => Ok(ImageMode::None),
        "all" => Ok(ImageMode::All),
        "caption" => Ok(ImageMode::Caption),
        "objects" => Ok(ImageMode::Objects),
        "ocr" => Ok(ImageMode::Ocr),
        _ => Err(format!(
            "unknown image mode `{value}`; expected none, all, caption, objects, or ocr"
        )),
    }
}

pub(crate) fn parse_vision_profile(value: &str) -> std::result::Result<VisionProfile, String> {
    match value {
        "fast" => Ok(VisionProfile::Fast),
        "balanced" => Ok(VisionProfile::Balanced),
        "accurate" => Ok(VisionProfile::Accurate),
        _ => Err(format!(
            "unknown vision profile `{value}`; expected fast, balanced, or accurate"
        )),
    }
}

pub(crate) fn parse_target(value: &str, name_mode: bool) -> Result<Target> {
    if value.is_empty() {
        bail!("target must not be empty");
    }

    let (read_stdin, rest) = match value.strip_prefix("stdin:") {
        Some(rest) => (true, rest),
        None => (false, value),
    };

    let (path, address) = if rest.is_empty() {
        (PathBuf::new(), None)
    } else if let Some((path, suffix)) = rest.rsplit_once(':') {
        let address = if suffix.is_empty() {
            None
        } else if name_mode {
            Some(TargetAddress::Name(suffix.to_owned()))
        } else if suffix.chars().all(|ch| ch.is_ascii_digit()) {
            let line = suffix
                .parse::<usize>()
                .with_context(|| format!("invalid target line: {suffix}"))?;
            if line == 0 {
                bail!("target line must be greater than zero");
            }
            Some(TargetAddress::Line(line))
        } else if is_line_hash(suffix) {
            Some(TargetAddress::Hash(suffix.to_ascii_lowercase()))
        } else {
            None
        };
        if address.is_some() {
            (PathBuf::from(path), address)
        } else {
            (PathBuf::from(rest), None)
        }
    } else {
        (PathBuf::from(rest), None)
    };

    if !read_stdin && path.as_os_str().is_empty() {
        bail!("target path must not be empty");
    }

    Ok(Target {
        path,
        address,
        read_stdin,
    })
}

fn is_line_hash(value: &str) -> bool {
    value.len() == 3 && value.chars().all(|ch| ch.is_ascii_hexdigit())
}

pub(crate) trait GitSelection {
    fn git_flags(&self) -> GitFlags;
}

macro_rules! impl_git_selection {
    ($($command:ty),+ $(,)?) => {
        $(
            impl GitSelection for $command {
                fn git_flags(&self) -> GitFlags {
                    GitFlags {
                        cached: self.cached,
                        others: self.others,
                        ignored: self.ignored,
                    }
                }
            }
        )+
    };
}

impl_git_selection!(DefCommand, RefsCommand, RenameCommand, SearchCommand);