Skip to main content

griz_core/
find.rs

1//! Finds code across files and returns matches a program can edit directly.
2//!
3//! Text queries take a literal or a regular expression; structural queries take
4//! an ast-grep pattern such as `foo($A, $$$REST)`. Every query answers with the
5//! same match shape, so an edit built from one kind works for the other.
6
7mod summary;
8mod text;
9
10use text::read as read_text;
11
12pub use summary::{FileSummary, FindFilesPage, find_files};
13
14use crate::{
15    ByteRange, content_hash, find_cache,
16    find_hits::{FileHits, Matcher},
17    find_position::{self, Cursor, to_match},
18    scope, structural,
19};
20use ast_grep_language::SupportLang;
21use ignore::{WalkBuilder, overrides::OverrideBuilder};
22use schemars::JsonSchema;
23use serde::{Deserialize, Serialize};
24use std::{
25    collections::{BTreeMap, HashSet},
26    ops::Range,
27    path::{Path, PathBuf},
28};
29
30/// What to search and where.
31#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
32pub struct FindQuery {
33    /// Files or directories to search. Directories honor `.gitignore`.
34    pub paths: Vec<PathBuf>,
35    /// Glob patterns a file must match, such as `**/*.rs`. `!` excludes.
36    #[serde(default)]
37    pub globs: Vec<String>,
38    /// Literal text to find. Give exactly one of `literal`, `regex`, `pattern`.
39    pub literal: Option<String>,
40    /// Regular expression to find, with capture groups.
41    pub regex: Option<String>,
42    /// Structural pattern with `$VAR` and `$$$VARS` metavariables.
43    #[serde(default)]
44    pub pattern: Option<String>,
45    /// Language for a structural pattern; defaults to each file's extension.
46    #[serde(default)]
47    pub language: Option<String>,
48    /// Matches to skip, for paging.
49    #[serde(default)]
50    pub offset: usize,
51    /// Most matches to return.
52    pub limit: usize,
53    /// Only match inside syntax nodes of these kinds, such as `comment` or
54    /// `string`, in enabled languages. Files in another language are
55    /// skipped once this is set.
56    #[serde(default)]
57    pub within: Vec<String>,
58}
59
60/// One match, carrying everything needed to edit exactly this text later.
61#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
62pub struct Match {
63    /// File containing the match.
64    pub path: PathBuf,
65    /// 1-based line.
66    pub line: usize,
67    /// 1-based column in characters.
68    pub column: usize,
69    /// Byte range in the file.
70    pub range: ByteRange,
71    /// Matched text.
72    pub text: String,
73    /// Regex capture groups in order; group 0 is the whole match and is omitted.
74    pub captures: Vec<Option<String>>,
75    /// Text captured by each structural metavariable, by name.
76    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
77    pub vars: BTreeMap<String, String>,
78    /// Byte range captured by each structural metavariable, by name.
79    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
80    pub var_ranges: BTreeMap<String, ByteRange>,
81    /// Fingerprint of the whole file when searched.
82    pub file_hash: String,
83}
84
85/// One page of matches.
86#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
87pub struct FindPage {
88    /// Matches on this page.
89    pub matches: Vec<Match>,
90    /// Matches across every file.
91    pub total: usize,
92    /// Files with at least one match.
93    pub files: usize,
94    /// Offset of the next page, when there is one.
95    pub next: Option<usize>,
96}
97
98/// A located span, before it becomes a [`Match`].
99#[derive(Debug, Clone)]
100pub struct Hit {
101    /// Byte range in the file.
102    pub range: Range<usize>,
103    /// Regex capture groups.
104    pub captures: Vec<Option<String>>,
105    /// Structural metavariables.
106    pub vars: BTreeMap<String, String>,
107    /// Byte range of each structural metavariable, by name.
108    pub var_ranges: BTreeMap<String, Range<usize>>,
109}
110
111/// Runs a query.
112///
113/// # Errors
114/// Returns a message for an invalid query or a filesystem traversal/read failure.
115/// Files that are not UTF-8 are skipped.
116pub fn find(query: &FindQuery) -> Result<FindPage, String> {
117    let matcher = Matcher::new(query)?;
118    let paths = files(query)?;
119    validate_within(query, &paths)?;
120    let mut page = FindPage::default();
121    for path in paths {
122        let window = (
123            query.offset.saturating_sub(page.total),
124            query.limit - page.matches.len(),
125        );
126        let Some(file) = text::page(&matcher, query, &path, window)? else {
127            continue;
128        };
129        page.files += file.files;
130        page.total += file.total;
131        page.matches.extend(file.matches);
132    }
133    let shown = query.offset + page.matches.len();
134    page.next = (shown < page.total).then_some(shown);
135    Ok(page)
136}
137
138fn page_in_file(
139    matcher: &Matcher,
140    query: &FindQuery,
141    path: &Path,
142    text: &str,
143    window: (usize, usize),
144) -> Result<FindPage, String> {
145    let mut page = FindPage::default();
146    if let Some(hits) = find_in_file(matcher, query, path, text, window)? {
147        collect_file(&mut page, hits, (path, text));
148        find_cache::remember(query, path, window, &page);
149    }
150    Ok(page)
151}
152
153/// Counts in-scope hits and selects this file's portion of the requested page.
154/// `None` skips a file whose language cannot be checked against `within`.
155fn find_in_file(
156    matcher: &Matcher,
157    query: &FindQuery,
158    path: &Path,
159    text: &str,
160    window: (usize, usize),
161) -> Result<Option<FileHits>, String> {
162    if query.within.is_empty() {
163        return matcher.hits(path, text, None, window).map(Some);
164    }
165    let Some(language) = structural::enabled_language(path) else {
166        return Ok(None);
167    };
168    let spans = scope::spans(language, text, &query.within);
169    matcher.hits(path, text, Some(&spans), window).map(Some)
170}
171
172/// Checks `within` before searching, once against every enabled language
173/// among the matched files.
174fn validate_within(query: &FindQuery, paths: &[PathBuf]) -> Result<(), String> {
175    if query.within.is_empty() {
176        return Ok(());
177    }
178    let languages: HashSet<SupportLang> = paths
179        .iter()
180        .filter_map(|path| structural::enabled_language(path))
181        .collect();
182    scope::validate(&query.within, &languages)
183}
184
185fn collect_file(page: &mut FindPage, hits: FileHits, (path, text): (&Path, &str)) {
186    if hits.total == 0 {
187        return;
188    }
189    page.files += 1;
190    page.total += hits.total;
191    if hits.hits.is_empty() {
192        return;
193    }
194    let hash = content_hash(text);
195    let mut cursor = Cursor::default();
196    for hit in hits.hits {
197        let position = find_position::position(&mut cursor, text, hit.range.start);
198        page.matches
199            .push(to_match(path, text, hit, &hash, position));
200    }
201}
202
203/// Every searchable file, sorted so pages are stable.
204fn files(query: &FindQuery) -> Result<Vec<PathBuf>, String> {
205    let mut found = Vec::new();
206    for root in &query.paths {
207        if root.is_file() {
208            found.push(root.clone());
209            continue;
210        }
211        collect_directory(root, &query.globs, &mut found)?;
212    }
213    found.sort();
214    found.dedup();
215    Ok(found)
216}
217
218fn collect_directory(
219    root: &Path,
220    globs: &[String],
221    found: &mut Vec<PathBuf>,
222) -> Result<(), String> {
223    let mut walk = WalkBuilder::new(root);
224    walk.overrides(overrides(root, globs)?);
225    for entry in walk.build() {
226        let entry = entry.map_err(|error| format!("walking: {error}"))?;
227        if entry.file_type().is_some_and(|kind| kind.is_file()) {
228            found.push(entry.into_path());
229        }
230    }
231    Ok(())
232}
233
234fn overrides(root: &Path, globs: &[String]) -> Result<ignore::overrides::Override, String> {
235    let mut builder = OverrideBuilder::new(root);
236    for glob in globs {
237        builder.add(glob).map_err(|error| error.to_string())?;
238    }
239    builder.build().map_err(|error| error.to_string())
240}