use host::file_hooks::{CellChanges, CellObserver, inside};
use kernel_apis::memory_records::Glob;
use serde_json::Value;
use std::collections::HashSet;
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::sync::{Arc, LazyLock, Mutex, PoisonError};
pub const PER_CELL: usize = 1;
pub const MAX_TEXT_CHARS: usize = 4000;
const DEFAULT_RULES: &[(&str, &str, &[&str])] = &[
(
"principle-test-behavior-not-implementation",
"You changed a test file",
&[
"**/tests/**",
"**/test/**",
"**/__tests__/**",
"**/test_*.py",
"**/*_test.*",
"**/*.test.*",
"**/*.spec.*",
],
),
(
"principle-minimize-reader-load",
"You changed documentation",
&["**/*.md", "**/docs/**"],
),
(
"typescript-best-practices",
"You changed TypeScript",
&["**/*.ts", "**/*.tsx"],
),
(
"principle-make-operations-idempotent",
"You changed a migration or a deploy step",
&[
"**/migrations/**",
"**/migration/**",
"**/alembic/**",
"**/*.sql",
"**/*.service",
"**/Dockerfile",
"**/.github/workflows/**",
],
),
(
"principle-explain-the-number",
"You changed a benchmark",
&["**/benches/**", "**/bench/**", "**/benchmarks/**", "**/*bench*.*"],
),
(
"principle-boundary-discipline",
"You changed an API or CLI boundary",
&["**/api/**", "**/routes/**", "**/handlers/**", "**/cli/src/**"],
),
(
"principle-type-system-discipline",
"You changed typed code",
&[
"**/*.rs",
"**/*.go",
"**/*.java",
"**/*.kt",
"**/*.swift",
"**/*.cs",
"**/*.scala",
],
),
];
pub const MANY_FILES: usize = 3;
pub const MANY_FILES_SKILL: &str = "rigor";
pub const MANY_FILES_PART: &str = "Playbooks";
pub const SHIP_SKILL: &str = "blast-radius";
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SelfReview {
Off,
Advise,
Require,
}
pub fn self_review(settings: &Value) -> SelfReview {
match settings["selfReview"].as_str() {
Some("off") => SelfReview::Off,
Some("advise") => SelfReview::Advise,
_ => SelfReview::Require,
}
}
fn unquoted(command: &str) -> String {
static QUOTED: LazyLock<regex::Regex> = LazyLock::new(|| regex::Regex::new(r#"'[^']*'|"[^"]*""#).expect("valid"));
QUOTED.replace_all(command, "''").into_owned()
}
fn ships(command: &str) -> bool {
static SHIP: LazyLock<regex::Regex> = LazyLock::new(|| {
regex::Regex::new(r"\bgit\s+(-C\s+\S+\s+)?(commit|push)\b|\bgh\s+pr\s+create\b").expect("valid")
});
SHIP.is_match(command)
}
fn pr_directory(command: &str, cwd: &Path) -> Option<PathBuf> {
static CREATE: LazyLock<regex::Regex> =
LazyLock::new(|| regex::Regex::new(r"\bgh\s+pr\s+create\b").expect("valid"));
directory_of(command, cwd, &CREATE)
}
fn push_directory(command: &str, cwd: &Path) -> Option<PathBuf> {
static PUSH: LazyLock<regex::Regex> = LazyLock::new(|| regex::Regex::new(r"\bgit\s+push\b").expect("valid"));
directory_of(command, cwd, &PUSH)
}
fn directory_of(command: &str, cwd: &Path, what: ®ex::Regex) -> Option<PathBuf> {
static CD: LazyLock<regex::Regex> =
LazyLock::new(|| regex::Regex::new(r"(?:^|[;&|(\n])\s*cd\s+([^\s;&|)']+)").expect("valid"));
let before = &command[..what.find(command)?.start()];
Some(match CD.captures_iter(before).last() {
Some(found) => cwd.join(&found[1]),
None => cwd.to_path_buf(),
})
}
fn git_value(dir: &Path, args: &[&str]) -> Option<String> {
let output = Command::new("git")
.args(args)
.current_dir(dir)
.env("GIT_OPTIONAL_LOCKS", "0")
.stdin(Stdio::null())
.stderr(Stdio::null())
.output()
.ok()?;
let text = String::from_utf8_lossy(&output.stdout).trim().to_string();
(output.status.success() && !text.is_empty()).then_some(text)
}
fn description_refusal(command: &str, dir: &Path) -> Option<String> {
static BODY: LazyLock<regex::Regex> = LazyLock::new(|| {
regex::Regex::new(r#"(?:--body-file|\s-F)(?:\s+|=)(?:"([^"]*)"|'([^']*)'|([^\s;&|)]+))"#).expect("valid")
});
let tree = git_value(dir, &["rev-parse", "HEAD^{tree}"])?;
let path = BODY
.captures(command)
.and_then(|found| found.iter().skip(1).flatten().next())
.map(|path| dir.join(path.as_str()));
let described = path
.and_then(|path| std::fs::read_to_string(path).ok())
.is_some_and(|text| text.lines().next() == Some(format!("<!-- ultron-description tree={tree} -->").as_str()));
(!described).then(|| {
format!(
"the description comes from the diff: run `import spec_api; path = spec_api.description(cwd={:?})` (it names what is still open, if anything), then open the pull request with `--body-file <path>` in place of --fill or --body. A commit after it needs a new one.",
dir.display().to_string()
)
})
}
fn stale_description(dir: &Path) -> Option<(String, String)> {
let tree = git_value(dir, &["rev-parse", "HEAD^{tree}"])?;
let git_dir = git_value(dir, &["rev-parse", "--absolute-git-dir"])?;
let text = std::fs::read_to_string(Path::new(&git_dir).join("ultron-review/description.md")).ok()?;
let described = text
.lines()
.next()?
.strip_prefix("<!-- ultron-description tree=")?
.strip_suffix(" -->")?;
(described != tree).then(|| (described.to_string(), tree))
}
fn receipt_refusal(dir: &Path) -> Option<String> {
let git = |args: &[&str]| git_value(dir, args);
let how = format!(
"commit the change, run `import review_api; review = await review_api.run(rlm, \"\", cwd={:?}); \
print(review.report)`, then run the command again",
dir.display().to_string()
);
let Some(tree) = git(&["rev-parse", "HEAD^{tree}"]) else {
return Some(format!(
"self-review comes first: no commit to review in {}; {how}.",
dir.display()
));
};
let receipt = git(&["rev-parse", "--absolute-git-dir"])
.and_then(|git_dir| std::fs::read_to_string(Path::new(&git_dir).join("ultron-review/receipt.json")).ok())
.and_then(|text| serde_json::from_str::<Value>(&text).ok())
.filter(|receipt| receipt["tree"] == tree.as_str());
let Some(receipt) = receipt else {
return Some(format!(
"self-review comes first: the committed tree {} has not been reviewed (a commit after a review needs a \
new one); {how}.",
&tree[..tree.len().min(8)]
));
};
let confirmed = receipt["confirmed"].as_u64().unwrap_or(u64::MAX);
let incomplete = receipt["incomplete"] != false;
let waived = receipt["waived"]
.as_str()
.is_some_and(|reason| !reason.trim().is_empty());
((confirmed > 0 || incomplete) && !waived).then(|| {
let unfinished = if incomplete {
" and did not finish (see its report)"
} else {
""
};
format!(
"self-review comes first: the review of this tree confirmed {confirmed} finding(s){unfinished}. Fix \
them, commit and review again (raise --budget for an unfinished one); or, for findings that are wrong \
or belong in a follow-up, record why with \
`review_api.waive(\"<reason>\", cwd={:?})` and say so in the pull request's description.",
dir.display().to_string()
)
})
}
pub fn excerpt(text: &str, file: &str) -> String {
if text.chars().count() <= MAX_TEXT_CHARS {
return text.to_string();
}
let bound = text.char_indices().nth(MAX_TEXT_CHARS).map_or(text.len(), |(at, _)| at);
let mut cut = text[..bound].rfind("\n\n").unwrap_or(bound);
while let Some(at) = text[..cut].rfind("\n\n")
&& text[at + 2..cut].starts_with('#')
{
cut = at;
}
let rest: Vec<&str> = text[cut..]
.lines()
.filter(|line| line.starts_with("## "))
.map(|line| line.trim_start_matches("## "))
.collect();
format!(
"{}\n\n[The rest, {}, is in {file}: read it before you act on it.]",
text[..cut].trim_end(),
rest.join(" · ")
)
}
pub fn section<'a>(text: &'a str, heading: &str) -> Option<&'a str> {
let start = text.find(&format!("\n## {heading}\n"))? + 1;
let end = text[start + 3..].find("\n## ").map_or(text.len(), |at| start + 3 + at);
Some(text[start..end].trim_end())
}
pub struct Rule {
pub skill: String,
pub situation: String,
pub paths: Vec<Glob>,
}
pub fn rules(settings: &Value) -> Vec<Rule> {
let always: HashSet<&str> = settings["alwaysSkills"]
.as_array()
.map(|names| names.iter().filter_map(Value::as_str).collect())
.unwrap_or_default();
let rule = |skill: &str, situation: &str, paths: &mut dyn Iterator<Item = &str>| {
let paths: Vec<Glob> = paths.filter_map(|pattern| Glob::new(pattern).ok()).collect();
(!skill.is_empty() && !paths.is_empty() && !always.contains(skill)).then(|| Rule {
skill: skill.to_string(),
situation: if situation.is_empty() {
"You changed a matching file".to_string()
} else {
situation.to_string()
},
paths,
})
};
match &settings["situationalSkills"] {
Value::Null => DEFAULT_RULES
.iter()
.filter_map(|(skill, situation, paths)| rule(skill, situation, &mut paths.iter().copied()))
.collect(),
Value::Array(items) => items
.iter()
.filter_map(|item| {
let paths = item["paths"].as_array()?;
rule(
item["skill"].as_str()?,
item["situation"].as_str().unwrap_or_default(),
&mut paths.iter().filter_map(Value::as_str),
)
})
.collect(),
_ => Vec::new(),
}
}
pub type Resolve = dyn Fn(&str) -> Option<(String, String)> + Send + Sync;
pub type Engineering = dyn Fn() -> bool + Send + Sync;
pub struct SituationalSkills {
rules: Vec<Rule>,
resolve: Box<Resolve>,
engineering: Box<Engineering>,
given: Mutex<HashSet<(String, String)>>,
changed: Mutex<HashSet<(String, String)>>,
self_review: SelfReview,
cwd: PathBuf,
}
impl SituationalSkills {
pub fn new(rules: Vec<Rule>, resolve: Box<Resolve>, engineering: Box<Engineering>) -> SituationalSkills {
SituationalSkills {
rules,
resolve,
engineering,
given: Mutex::new(HashSet::new()),
changed: Mutex::new(HashSet::new()),
self_review: SelfReview::Advise,
cwd: PathBuf::new(),
}
}
pub fn with_self_review(mut self, self_review: SelfReview, cwd: &Path) -> SituationalSkills {
(self.self_review, self.cwd) = (self_review, cwd.to_path_buf());
self
}
fn give_part(&self, lane: &str, skill: &str, head: String, part: &str) -> Option<String> {
let mut given = self.given.lock().unwrap_or_else(PoisonError::into_inner);
if given.contains(&(lane.to_string(), skill.to_string())) {
return None;
}
let (file, text) = (self.resolve)(skill)?;
given.insert((lane.to_string(), skill.to_string()));
let dir = Path::new(&file)
.parent()
.map(|dir| dir.display().to_string())
.unwrap_or_default();
Some(match section(text.trim(), part) {
Some(body) => format!(
"{head}\n{body}\n\n[Paths are relative to {dir}. Pick the playbook now and read it before the next edit; \
the whole skill is {file}.]"
),
None => format!("{head}\n{}", excerpt(text.trim(), &file)),
})
}
fn give(&self, lane: &str, skill: &str, head: String) -> Option<String> {
let mut given = self.given.lock().unwrap_or_else(PoisonError::into_inner);
if given.contains(&(lane.to_string(), skill.to_string())) {
return None;
}
let (file, text) = (self.resolve)(skill)?;
given.insert((lane.to_string(), skill.to_string()));
Some(format!("{head}\n{}", excerpt(text.trim(), &file)))
}
pub fn many_files(&self, lane: &str, paths: &[String]) -> Option<String> {
let count = {
let mut changed = self.changed.lock().unwrap_or_else(PoisonError::into_inner);
changed.extend(paths.iter().map(|path| (lane.to_string(), path.clone())));
changed.iter().filter(|(l, _)| l == lane).count()
};
(count >= MANY_FILES).then(|| {
self.give_part(
lane,
MANY_FILES_SKILL,
format!("[skill] You changed {count} files: {MANY_FILES_SKILL} applies from here on."),
MANY_FILES_PART,
)
})?
}
pub fn text_for(&self, lane: &str, paths: &[String]) -> Vec<String> {
let mut out = Vec::new();
for rule in &self.rules {
if out.len() == PER_CELL {
break;
}
let Some(path) = paths
.iter()
.find(|path| rule.paths.iter().any(|glob| glob.matches(path)))
else {
continue;
};
let head = format!(
"[skill] {} ({path}): {} applies from here on.",
rule.situation, rule.skill
);
out.extend(self.give(lane, &rule.skill, head));
}
out.extend(self.many_files(lane, paths));
out
}
}
impl CellObserver for SituationalSkills {
fn enabled(&self) -> bool {
(!self.rules.is_empty() || self.self_review != SelfReview::Off) && (self.engineering)()
}
fn cell_changed(&self, changes: &CellChanges, cwd: &Path, lane: &str) -> Vec<String> {
let paths: Vec<String> = changes
.checked
.iter()
.filter_map(|path| {
inside(cwd, path).or_else(|| {
let dir = path.ancestors().skip(1).find(|dir| dir.is_dir())?;
inside(&host::loki_guard::git_root(dir)?, path)
})
})
.map(|relative| relative.replace('\\', "/"))
.collect();
self.text_for(lane, &paths)
}
fn before_shell(&self, typed: &str, lane: &str) -> Option<String> {
let command = unquoted(typed);
if self.self_review == SelfReview::Off || !ships(&command) {
return None;
}
let head = format!(
"{SHIP_SKILL} comes first: check what this change could break outside its diff, then run the command \
again (it is refused once per lane)."
);
self.give(lane, SHIP_SKILL, head).or_else(|| {
if self.self_review != SelfReview::Require {
return None;
}
if let Some(dir) = pr_directory(&command, &self.cwd) {
return receipt_refusal(&dir).or_else(|| description_refusal(typed, &dir));
}
let dir = push_directory(&command, &self.cwd)?;
let (described, tree) = stale_description(&dir)?;
let mut given = self.given.lock().unwrap_or_else(PoisonError::into_inner);
given
.insert((lane.to_string(), format!("description {tree}")))
.then(|| {
format!(
"the description was written for tree {}, and this push carries {}: an open pull request would \
describe a change it no longer carries. Run the push again (it is refused once per tree); then \
review the new tree, run `spec_api.description(cwd={:?})` and update the pull request with \
`gh pr edit --body-file <path>`.",
&described[..described.len().min(8)],
&tree[..tree.len().min(8)],
dir.display().to_string()
)
})
})
}
}
pub fn session_observer(
settings: &Value,
cwd: &Path,
resolve: Box<Resolve>,
engineering: Box<Engineering>,
) -> Option<Arc<dyn CellObserver>> {
let (rules, self_review) = (rules(settings), self_review(settings));
(!rules.is_empty() || self_review != SelfReview::Off).then(|| {
Arc::new(SituationalSkills::new(rules, resolve, engineering).with_self_review(self_review, cwd))
as Arc<dyn CellObserver>
})
}