Skip to main content

cellix_agent/context/
checks.rs

1//! Gentle checks on what an agent works from. They say what Cellix can tell from the files
2//! alone and never stop the agent. Whether two instructions really disagree in meaning is for
3//! the agent to judge; these only notice the same command told to run and never to run.
4
5use std::path::{Path, PathBuf};
6
7use super::{Agent, Context, Instruction, ItemKind, LARGE_CHARS, estimate_tokens};
8
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub enum CheckKind {
11    /// Two files say opposite things about the same command.
12    Opposite,
13    /// An `@import` names a file that isn't there.
14    MissingImport,
15    /// The agent reads only part of the file.
16    CutOff,
17    /// A large file loaded into every session.
18    Large,
19    /// A skill or subagent the agent can't tell when to use.
20    NoDescription,
21    /// A hook runs a file that isn't there.
22    MissingFile,
23    /// The project's instructions are in a file this agent doesn't read.
24    NotRead,
25}
26
27impl CheckKind {
28    pub fn label(self) -> &'static str {
29        match self {
30            CheckKind::Opposite => "Say opposite things",
31            CheckKind::MissingImport => "Import not found",
32            CheckKind::CutOff => "Cut off",
33            CheckKind::Large => "Large",
34            CheckKind::NoDescription => "No description",
35            CheckKind::MissingFile => "Missing file",
36            CheckKind::NotRead => "Not read by this agent",
37        }
38    }
39
40    /// Whether it changes what the agent does, rather than how well.
41    pub fn warns(self) -> bool {
42        matches!(
43            self,
44            CheckKind::Opposite | CheckKind::MissingImport | CheckKind::CutOff | CheckKind::NotRead
45        )
46    }
47}
48
49#[derive(Clone, Debug, PartialEq)]
50pub struct Check {
51    pub kind: CheckKind,
52    pub message: String,
53    pub path: PathBuf,
54    /// 1-based.
55    pub line: Option<usize>,
56    /// The other side, for two files that disagree.
57    pub other: Option<(PathBuf, usize)>,
58}
59
60const NEGATIVE: [&str; 8] = [
61    "never ",
62    "don't ",
63    "do not ",
64    "avoid ",
65    "must not ",
66    "mustn't ",
67    "should not ",
68    "shouldn't ",
69];
70
71pub fn checks(agent: Agent, project: &Path, context: &Context) -> Vec<Check> {
72    let mut out = Vec::new();
73    let present: Vec<&Instruction> = context
74        .instructions
75        .iter()
76        .filter(|i| i.exists() && i.later.is_none())
77        .collect();
78    out.extend(opposites(&present));
79    for file in &context.instructions {
80        if let (Some((by, line)), false) = (&file.imported_by, file.exists()) {
81            out.push(Check {
82                kind: CheckKind::MissingImport,
83                message: format!(
84                    "{} doesn't exist, so nothing is loaded there",
85                    short(&file.path, project)
86                ),
87                path: by.clone(),
88                line: Some(*line),
89                other: None,
90            });
91        }
92        if let Some(limit) = file.limit
93            && file.lines() > limit
94        {
95            out.push(Check {
96                kind: CheckKind::CutOff,
97                message: format!(
98                    "{} has {} lines; {} reads the first {limit}",
99                    name(&file.path),
100                    file.lines(),
101                    agent.name()
102                ),
103                path: file.path.clone(),
104                line: Some(limit + 1),
105                other: None,
106            });
107        }
108        if file
109            .text
110            .as_ref()
111            .is_some_and(|t| t.chars().count() > LARGE_CHARS)
112            && file.later.is_none()
113        {
114            out.push(Check {
115                kind: CheckKind::Large,
116                message: format!(
117                    "{} is {} lines (≈{}k tokens), loaded into every session",
118                    short(&file.path, project),
119                    file.lines(),
120                    estimate_tokens(file.loaded()) / 1000
121                ),
122                path: file.path.clone(),
123                line: None,
124                other: None,
125            });
126        }
127    }
128    for item in &context.items {
129        if matches!(item.kind, ItemKind::Skill | ItemKind::Subagent) && item.about.trim().is_empty()
130        {
131            out.push(Check {
132                kind: CheckKind::NoDescription,
133                message: format!(
134                    "{} {}: the agent sees only its name, so can't tell when to use it",
135                    capital(item.kind.label()),
136                    item.name
137                ),
138                path: item.path.clone(),
139                line: None,
140                other: None,
141            });
142        }
143        if item.kind == ItemKind::Hook {
144            for script in scripts(&item.about, project) {
145                if !script.exists() {
146                    out.push(Check {
147                        kind: CheckKind::MissingFile,
148                        message: format!(
149                            "Hook {} runs {}, which isn't there",
150                            item.name,
151                            short(&script, project)
152                        ),
153                        path: item.path.clone(),
154                        line: item.line,
155                        other: None,
156                    });
157                }
158            }
159        }
160    }
161    out.extend(not_read(agent, project, context));
162    out
163}
164
165fn capital(s: &str) -> String {
166    let mut c = s.chars();
167    c.next()
168        .map(|f| f.to_uppercase().chain(c).collect())
169        .unwrap_or_default()
170}
171
172fn name(path: &Path) -> String {
173    path.file_name()
174        .map(|n| n.to_string_lossy().into_owned())
175        .unwrap_or_default()
176}
177
178/// A path as the user would say it: inside the project, from its top; at home, with `~`.
179pub(crate) fn short(path: &Path, project: &Path) -> String {
180    if let Ok(rel) = path.strip_prefix(project) {
181        return rel.display().to_string();
182    }
183    if let Some(home) = std::env::var_os("HOME")
184        && let Ok(rel) = path.strip_prefix(&home)
185    {
186        return format!("~/{}", rel.display());
187    }
188    path.display().to_string()
189}
190
191/// The commands a line names in backticks, lower case. A one-word span after a longer one
192/// borrows its first word, so "Never run `cargo build`, `test`" names `cargo test` too.
193fn commands(line: &str) -> Vec<String> {
194    let spans: Vec<&str> = line.split('`').skip(1).step_by(2).collect();
195    let mut out = Vec::new();
196    let mut head: Option<String> = None;
197    for span in spans {
198        let words: Vec<String> = span.split_whitespace().map(str::to_lowercase).collect();
199        match words.len() {
200            0 => {}
201            1 => {
202                if let Some(h) = &head {
203                    out.push(format!("{h} {}", words[0]));
204                }
205                out.push(words[0].clone());
206            }
207            _ => {
208                head = Some(words[0].clone());
209                out.push(words.join(" "));
210            }
211        }
212    }
213    out.retain(|c| c.len() > 2);
214    out
215}
216
217fn negative(line: &str) -> bool {
218    let lower = format!(" {}", line.to_lowercase().replace(['*', '_'], ""));
219    NEGATIVE.iter().any(|n| lower.contains(&format!(" {n}")))
220}
221
222/// Lines outside fenced code, numbered from 1.
223fn prose_lines(text: &str) -> Vec<(usize, &str)> {
224    let mut fenced = false;
225    let mut out = Vec::new();
226    for (i, line) in text.lines().enumerate() {
227        if line.trim_start().starts_with("```") || line.trim_start().starts_with("~~~") {
228            fenced = !fenced;
229            continue;
230        }
231        if !fenced {
232            out.push((i + 1, line));
233        }
234    }
235    out
236}
237
238fn opposites(files: &[&Instruction]) -> Vec<Check> {
239    struct Said<'a> {
240        file: usize,
241        line: usize,
242        negative: bool,
243        command: String,
244        path: &'a Path,
245    }
246    let mut said = Vec::new();
247    for (f, file) in files.iter().enumerate() {
248        for (n, line) in prose_lines(file.loaded()) {
249            let neg = negative(line);
250            for command in commands(line) {
251                said.push(Said {
252                    file: f,
253                    line: n,
254                    negative: neg,
255                    command,
256                    path: &file.path,
257                });
258            }
259        }
260    }
261    let mut out: Vec<Check> = Vec::new();
262    for no in said.iter().filter(|s| s.negative) {
263        for yes in said
264            .iter()
265            .filter(|s| !s.negative && s.file != no.file && s.command == no.command)
266        {
267            // Only commands, not single words like `test` that turn up everywhere.
268            if !yes.command.contains(' ') {
269                continue;
270            }
271            let pair = (yes.path.to_path_buf(), no.path.to_path_buf());
272            if out.iter().any(|c| {
273                (
274                    c.path.clone(),
275                    c.other.as_ref().map(|o| o.0.clone()).unwrap_or_default(),
276                ) == pair
277                    && c.message.contains(&yes.command)
278            }) {
279                continue;
280            }
281            out.push(Check {
282                kind: CheckKind::Opposite,
283                message: format!(
284                    "“{}”: run in {}, never in {}",
285                    yes.command,
286                    name(yes.path),
287                    name(no.path)
288                ),
289                path: yes.path.to_path_buf(),
290                line: Some(yes.line),
291                other: Some((no.path.to_path_buf(), no.line)),
292            });
293        }
294    }
295    out
296}
297
298/// Script files a hook's command runs: words that look like a path to a script, with the
299/// project's folder put in for `$CLAUDE_PROJECT_DIR`.
300fn scripts(command: &str, project: &Path) -> Vec<PathBuf> {
301    let project_text = project.to_string_lossy();
302    let expanded = command
303        .replace("\"$CLAUDE_PROJECT_DIR\"", &project_text)
304        .replace("${CLAUDE_PROJECT_DIR}", &project_text)
305        .replace("$CLAUDE_PROJECT_DIR", &project_text);
306    expanded
307        .split(|c: char| c.is_whitespace() || c == ';' || c == '&' || c == '|')
308        .map(|w| w.trim_matches(|c| c == '"' || c == '\''))
309        .filter(|w| {
310            let script = [".sh", ".py", ".js", ".mjs", ".ts", ".rb", ".pl"]
311                .iter()
312                .any(|e| w.ends_with(e));
313            script && (w.contains('/') || w.starts_with('.'))
314        })
315        .filter(|w| !w.contains('$') && !w.contains('*'))
316        .map(|w| {
317            let path = Path::new(w);
318            if path.is_absolute() {
319                path.to_path_buf()
320            } else {
321                project.join(path)
322            }
323        })
324        .collect()
325}
326
327/// The project has instructions, but in a file this agent doesn't read.
328fn not_read(agent: Agent, project: &Path, context: &Context) -> Vec<Check> {
329    let has = |n: &str| project.join(n).is_file();
330    let project_files = context
331        .instructions
332        .iter()
333        .any(|i| i.exists() && i.path.starts_with(project) && i.imported_by.is_none());
334    let note = |message: &str, path: &str| Check {
335        kind: CheckKind::NotRead,
336        message: message.to_string(),
337        path: project.join(path),
338        line: None,
339        other: None,
340    };
341    match agent {
342        Agent::Claude if has("AGENTS.md") && !project_files => {
343            vec![note(
344                "Claude Code reads CLAUDE.md; this project's instructions are in AGENTS.md",
345                "AGENTS.md",
346            )]
347        }
348        Agent::Codex if has("CLAUDE.md") && !has("AGENTS.md") => {
349            vec![note(
350                "Codex reads AGENTS.md; this project's instructions are in CLAUDE.md",
351                "CLAUDE.md",
352            )]
353        }
354        Agent::Gemini if has("AGENTS.md") && !project_files => {
355            vec![note(
356                "Gemini CLI reads GEMINI.md; this project's instructions are in AGENTS.md",
357                "AGENTS.md",
358            )]
359        }
360        _ => Vec::new(),
361    }
362}
363
364#[cfg(test)]
365mod tests {
366    use super::*;
367
368    #[test]
369    fn a_short_command_borrows_the_one_before() {
370        assert_eq!(
371            commands("**Never run `cargo build`, `test`, `check` directly.**"),
372            ["cargo build", "cargo test", "test", "cargo check", "check"]
373        );
374        assert!(negative("**Never run `cargo build` directly.**"));
375        assert!(!negative("Run tests with `cargo test` first."));
376    }
377
378    #[test]
379    fn hook_scripts_are_found_in_the_project() {
380        let found = scripts(
381            "bash \"$CLAUDE_PROJECT_DIR\"/harness/hooks/guard.sh && echo ok",
382            Path::new("/p"),
383        );
384        assert_eq!(found, [PathBuf::from("/p/harness/hooks/guard.sh")]);
385        assert!(scripts("harness/x status", Path::new("/p")).is_empty());
386    }
387}