1use 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 Opposite,
13 MissingImport,
15 CutOff,
17 Large,
19 NoDescription,
21 MissingFile,
23 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 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 pub line: Option<usize>,
56 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
178pub(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
191fn 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
222fn 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 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
298fn 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
327fn 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}