use colored::Colorize;
use std::fmt;
use std::path::Path;
use std::process::Command;
use crate::models::{CheckStatus, ProjectStack};
use crate::modules::stack_detector::{
detect_stack, extract_version, parse_key_value, python_version_from_pyproject, read_clean,
};
const NODE_MIN: SemVer = SemVer::new(14, 0, 0);
const NODE_RECOMMENDED: SemVer = SemVer::new(18, 0, 0);
const PYTHON_MIN: SemVer = SemVer::new(3, 8, 0);
const PYTHON_RECOMMENDED: SemVer = SemVer::new(3, 9, 0);
const RUST_MIN: SemVer = SemVer::new(1, 56, 0);
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VersionReport {
pub status: CheckStatus,
pub actual_version: String,
pub required_version: Option<String>,
pub message: String,
pub remediation: Option<String>,
}
impl VersionReport {
pub fn is_pass(&self) -> bool {
self.status == CheckStatus::Pass
}
pub fn status_label(&self) -> String {
match self.status {
CheckStatus::Pass => "PASS".green().bold().to_string(),
CheckStatus::Warn => "WARN".yellow().bold().to_string(),
CheckStatus::Fail => "FAIL".red().bold().to_string(),
}
}
}
pub fn validate_runtime_version(stack: &ProjectStack, actual: &str) -> VersionReport {
match stack {
ProjectStack::Node { .. } => check_node(actual, None),
ProjectStack::Python { .. } => check_python(actual, None),
ProjectStack::Rust { .. } => check_rust(actual, None),
ProjectStack::Go { .. } | ProjectStack::Java { .. } => report_pass(actual, "Runtime version is valid for this stack.", None, None),
ProjectStack::Docker => report_warn(
actual,
"Docker is a container runtime — there is no runtime version to validate.",
None,
None,
),
ProjectStack::Unknown => report_warn(
actual,
"No recognizable stack detected, so the runtime version could not be validated.",
None,
None,
),
}
}
pub fn validate_project_runtime(
repo_root: &str,
stack: &ProjectStack,
actual: &str,
) -> VersionReport {
let root = Path::new(repo_root);
match stack {
ProjectStack::Node { .. } => check_node(actual, read_engines_node(root).as_deref()),
ProjectStack::Python { .. } => {
check_python(actual, read_pyproject_requirement(root).as_deref())
}
ProjectStack::Rust { .. } => {
check_rust(actual, read_rust_toolchain_requirement(root).as_deref())
}
_ => validate_runtime_version(stack, actual),
}
}
pub fn validate_installed_runtime(repo_root: &str) -> Option<VersionReport> {
let stack = detect_stack(repo_root);
let probes: &[(&str, &str)] = match stack {
ProjectStack::Node { .. } => &[("node", "--version")],
ProjectStack::Python { .. } => &[("python", "--version"), ("python3", "--version")],
ProjectStack::Rust { .. } => &[("rustc", "--version")],
_ => return None,
};
for (cmd, flag) in probes {
if let Ok(output) = Command::new(cmd).arg(flag).output() {
let raw = String::from_utf8_lossy(&output.stdout);
let raw_stderr = String::from_utf8_lossy(&output.stderr);
let combined = if raw.trim().is_empty() {
raw_stderr.to_string()
} else {
raw.to_string()
};
let actual = extract_version(&combined)?;
return Some(validate_project_runtime(repo_root, &stack, &actual));
}
}
None
}
fn check_node(actual: &str, engines_req: Option<&str>) -> VersionReport {
let parsed = match SemVer::parse(actual) {
Some(v) => v,
None => {
return report_fail(
actual,
&format!(
"Node could not be validated: '{actual}' is not a valid semantic version."
),
None,
None,
);
}
};
if parsed < NODE_MIN {
return report_fail(
actual,
&format!(
"Node v{parsed} is too old. Node {} or newer is required.",
required_label(NODE_MIN)
),
Some("14.0.0".to_string()),
Some("Install a supported Node runtime: `nvm install 18 && nvm use 18`"),
);
}
if let Some(req) = semver_floor(engines_req) {
if parsed < req {
return report_fail(
actual,
&format!(
"engines.node requires Node {engines}, but v{parsed} is installed.",
engines = engines_req.unwrap_or_default()
),
Some(req.to_string()),
Some("Upgrade Node to match engines.node or relax the pin in package.json"),
);
}
}
if parsed < NODE_RECOMMENDED {
return report_warn(
actual,
&format!("Node v{parsed} works, but Node 18.0.0+ is recommended.",),
Some(format!("{}", NODE_RECOMMENDED)),
Some("Consider installing Node 18+: `nvm install 18 && nvm use 18`"),
);
}
report_pass(
actual,
&format!("Node v{parsed} meets the recommended version (>= 18.0.0)"),
Some(format!("{}", NODE_RECOMMENDED)),
None,
)
}
fn check_python(actual: &str, pyproject_req: Option<&str>) -> VersionReport {
let parsed = match SemVer::parse(actual) {
Some(v) => v,
None => {
return report_fail(
actual,
&format!(
"Python could not be validated: '{actual}' is not a valid semantic version."
),
None,
None,
);
}
};
if parsed < PYTHON_MIN {
return report_fail(
actual,
&format!(
"Python v{parsed} is too old. Python {} or newer is required.",
required_label(PYTHON_MIN)
),
Some("3.8.0".to_string()),
Some("Install a supported Python: https://www.python.org/downloads/"),
);
}
if let Some(req) = semver_floor(pyproject_req) {
if parsed < req {
return report_fail(
actual,
&format!(
"pyproject.toml requires Python {pyproject}, but v{parsed} is installed.",
pyproject = pyproject_req.unwrap_or_default()
),
Some(req.to_string()),
Some("Install the version pinned by your project (pyenv recommended)"),
);
}
}
if parsed < PYTHON_RECOMMENDED {
return report_warn(
actual,
&format!("Python v{parsed} works, but Python 3.9.0+ is recommended."),
Some(format!("{}", PYTHON_RECOMMENDED)),
Some("Consider installing Python 3.9+: https://www.python.org/downloads/"),
);
}
report_pass(
actual,
&format!("Python v{parsed} meets the recommended version (>= 3.9.0)"),
Some(format!("{}", PYTHON_RECOMMENDED)),
None,
)
}
fn check_rust(actual: &str, toolchain_req: Option<&str>) -> VersionReport {
let parsed = match SemVer::parse(actual) {
Some(v) => v,
None => {
return report_fail(
actual,
&format!(
"Rust could not be validated: '{actual}' is not a valid semantic version."
),
None,
None,
);
}
};
if parsed < RUST_MIN {
return report_fail(
actual,
&format!(
"Rust v{parsed} is too old. Rust {} or newer is required.",
required_label(RUST_MIN)
),
Some("1.56.0".to_string()),
Some("Update your toolchain: `rustup update stable`"),
);
}
if let Some(req) = semver_floor(toolchain_req) {
if parsed < req {
return report_fail(
actual,
&format!(
"rust-toolchain pins Rust {toolchain}, but v{parsed} is installed.",
toolchain = toolchain_req
.map(|t| t.split_whitespace().next().unwrap_or(t))
.unwrap_or_default()
),
Some(req.to_string()),
Some("Run `rustup toolchain install <pinned-version>` to match rust-toolchain"),
);
}
}
report_pass(
actual,
&format!("Rust v{parsed} meets the minimum requirement (>= 1.56.0)"),
Some(format!("{}", RUST_MIN)),
None,
)
}
fn read_engines_node(root: &Path) -> Option<String> {
let content = read_clean(root.join("package.json")).ok()?;
let json: serde_json::Value = serde_json::from_str(&content).ok()?;
json.pointer("/engines/node")
.and_then(|v| v.as_str())
.map(str::to_string)
}
fn read_pyproject_requirement(root: &Path) -> Option<String> {
let content = read_clean(root.join("pyproject.toml")).ok()?;
python_version_from_pyproject(&content)
}
fn read_rust_toolchain_requirement(root: &Path) -> Option<String> {
if let Ok(content) = read_clean(root.join("rust-toolchain.toml")) {
let mut in_toolchain = false;
for line in content.lines() {
let trimmed = line.trim();
if trimmed.starts_with('[') {
in_toolchain = trimmed == "[toolchain]";
continue;
}
if in_toolchain {
if let Some(channel) = parse_key_value(trimmed, "channel") {
if !channel.is_empty() {
return Some(channel);
}
}
}
}
}
if let Ok(content) = read_clean(root.join("rust-toolchain")) {
let trimmed = content.trim();
if !trimmed.is_empty() {
return Some(trimmed.to_string());
}
}
None
}
fn semver_floor(requirement: Option<&str>) -> Option<SemVer> {
let raw = extract_version(requirement?)?;
SemVer::parse(&raw)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct SemVer {
major: u64,
minor: u64,
patch: u64,
}
impl SemVer {
const fn new(major: u64, minor: u64, patch: u64) -> Self {
Self {
major,
minor,
patch,
}
}
pub fn parse(raw: &str) -> Option<SemVer> {
let core = raw
.trim()
.trim_start_matches('v')
.split(['-', '+'])
.next()?;
if core.is_empty() {
return None;
}
let parts: Vec<&str> = core.split('.').collect();
if parts.len() > 3
|| parts
.iter()
.any(|p| p.is_empty() || !p.chars().all(|c| c.is_ascii_digit()))
{
return None;
}
let mut nums = [0u64; 3];
for (i, part) in parts.iter().enumerate() {
nums[i] = part.parse().ok()?;
}
Some(SemVer::new(nums[0], nums[1], nums[2]))
}
}
impl fmt::Display for SemVer {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}.{}.{}", self.major, self.minor, self.patch)
}
}
fn required_label(version: SemVer) -> String {
format!("v{version}")
}
fn report_pass(
actual: &str,
message: &str,
required: Option<String>,
remediation: Option<&str>,
) -> VersionReport {
VersionReport {
status: CheckStatus::Pass,
actual_version: actual.to_string(),
required_version: required,
message: message.to_string(),
remediation: remediation.map(str::to_string),
}
}
fn report_warn(
actual: &str,
message: &str,
required: Option<String>,
remediation: Option<&str>,
) -> VersionReport {
VersionReport {
status: CheckStatus::Warn,
actual_version: actual.to_string(),
required_version: required,
message: message.to_string(),
remediation: remediation.map(str::to_string),
}
}
fn report_fail(
actual: &str,
message: &str,
required: Option<String>,
remediation: Option<&str>,
) -> VersionReport {
VersionReport {
status: CheckStatus::Fail,
actual_version: actual.to_string(),
required_version: required,
message: message.to_string(),
remediation: remediation.map(str::to_string),
}
}
#[cfg(test)]
mod tests {
use super::*;
fn node() -> ProjectStack {
ProjectStack::Node {
version: String::new(),
package_manager: "npm".to_string(),
}
}
fn python() -> ProjectStack {
ProjectStack::Python {
version: String::new(),
}
}
fn rust() -> ProjectStack {
ProjectStack::Rust {
version: String::new(),
}
}
#[test]
fn parses_full_partial_and_prefixed_versions() {
assert_eq!(SemVer::parse("18.12.0"), Some(SemVer::new(18, 12, 0)));
assert_eq!(SemVer::parse("v18.12.0"), Some(SemVer::new(18, 12, 0)));
assert_eq!(SemVer::parse("18.2"), Some(SemVer::new(18, 2, 0)));
assert_eq!(SemVer::parse("18"), Some(SemVer::new(18, 0, 0)));
assert_eq!(SemVer::parse(" 3.10.9 "), Some(SemVer::new(3, 10, 9)));
}
#[test]
fn rejects_non_version_strings() {
assert_eq!(SemVer::parse("lts"), None);
assert_eq!(SemVer::parse("stable"), None);
assert_eq!(SemVer::parse(""), None);
assert_eq!(SemVer::parse("a.b.c"), None);
assert_eq!(SemVer::parse("18.12.0.1"), None);
assert_eq!(SemVer::parse("18..0"), None);
}
#[test]
fn orders_versions_correctly() {
let v = |s: &str| SemVer::parse(s).unwrap();
assert!(v("18.12.0") > v("18.2.0"));
assert!(v("18.2.0") > v("18.0.9"));
assert!(v("18.0.0") > v("17.99.99"));
assert!(v("3.9.0") > v("3.8.9"));
assert!(v("1.85.0") > v("1.56.0"));
assert!(v("1.56.0") == v("1.56"));
}
#[test]
fn node_pass_when_recommended() {
let report = validate_runtime_version(&node(), "18.12.0");
assert_eq!(report.status, CheckStatus::Pass);
assert!(report.message.contains("18.12.0"));
}
#[test]
fn node_warns_when_below_recommended_but_above_min() {
let report = validate_runtime_version(&node(), "16.3.1");
assert_eq!(report.status, CheckStatus::Warn);
assert!(report.message.contains("recommended"));
}
#[test]
fn node_fails_below_hard_minimum() {
let report = validate_runtime_version(&node(), "12.22.0");
assert_eq!(report.status, CheckStatus::Fail);
assert!(report.message.contains("14.0.0"));
assert!(report.remediation.is_some());
}
#[test]
fn node_engines_floor_is_enforced() {
let report = check_node("18.12.0", Some(">=20.0.0"));
assert_eq!(report.status, CheckStatus::Fail);
assert!(report.message.contains("engines.node"));
assert!(report.message.contains("20.0.0"));
let report = check_node("16.4.0", Some(">=16.0.0 <20"));
assert_eq!(report.status, CheckStatus::Warn);
let report = check_node("19.0.0", Some("^18.0.0"));
assert_eq!(report.status, CheckStatus::Pass);
}
#[test]
fn node_rejects_invalid_version() {
let report = validate_runtime_version(&node(), "latest");
assert_eq!(report.status, CheckStatus::Fail);
assert!(report.message.contains("not a valid semantic version"));
}
#[test]
fn python_pass_when_recommended() {
let report = validate_runtime_version(&python(), "3.12.0");
assert_eq!(report.status, CheckStatus::Pass);
}
#[test]
fn python_warns_when_below_recommended() {
let report = validate_runtime_version(&python(), "3.8.5");
assert_eq!(report.status, CheckStatus::Warn);
assert!(report.message.contains("3.9.0"));
}
#[test]
fn python_fails_below_hard_minimum() {
let report = validate_runtime_version(&python(), "3.7.9");
assert_eq!(report.status, CheckStatus::Fail);
assert!(report.message.contains("3.8.0"));
}
#[test]
fn python_pyproject_floor_is_enforced() {
let report = check_python("3.10.0", Some(">=3.11"));
assert_eq!(report.status, CheckStatus::Fail);
assert!(report.message.contains("pyproject.toml"));
let report = check_python("3.10.0", Some(">=3.9"));
assert_eq!(report.status, CheckStatus::Pass);
}
#[test]
fn rust_pass_when_above_minimum() {
let report = validate_runtime_version(&rust(), "1.85.0");
assert_eq!(report.status, CheckStatus::Pass);
}
#[test]
fn rust_fails_below_minimum() {
let report = validate_runtime_version(&rust(), "1.55.0");
assert_eq!(report.status, CheckStatus::Fail);
assert!(report.message.contains("1.56.0"));
}
#[test]
fn rust_toolchain_floor_is_enforced() {
let report = check_rust("1.76.0", Some("1.80.0"));
assert_eq!(report.status, CheckStatus::Fail);
assert!(report.message.contains("1.80.0"));
let report = check_rust("1.80.0", Some("1.80.0"));
assert_eq!(report.status, CheckStatus::Pass);
}
#[test]
fn rust_nightly_channel_is_not_a_version_gate() {
let report = check_rust("1.76.0", Some("nightly-2026-01-01"));
assert_eq!(report.status, CheckStatus::Pass);
}
#[test]
fn docker_and_unknown_are_warns() {
let docker = validate_runtime_version(&ProjectStack::Docker, "1.0.0");
assert_eq!(docker.status, CheckStatus::Warn);
let unknown = validate_runtime_version(&ProjectStack::Unknown, "1.0.0");
assert_eq!(unknown.status, CheckStatus::Warn);
}
#[test]
fn validate_project_runtime_reads_engines_from_fixture() {
let dir =
std::env::temp_dir().join(format!("runtime_validator_fixture_{}", std::process::id()));
std::fs::create_dir_all(&dir).expect("create fixture");
std::fs::write(
dir.join("package.json"),
r#"{ "engines": { "node": ">=20.0.0" } }"#,
)
.expect("write fixture");
let report = validate_project_runtime(dir.to_str().expect("utf8"), &node(), "18.12.0");
assert_eq!(report.status, CheckStatus::Fail);
assert!(report.message.contains("engines.node"));
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn examples_of_pass_warn_fail_outputs() {
let stacks = [
("Node", node(), "18.12.0"),
("Node", node(), "16.3.1"),
("Node", node(), "12.22.0"),
("Python", python(), "3.12.0"),
("Python", python(), "3.8.5"),
("Python", python(), "3.7.9"),
("Rust", rust(), "1.85.0"),
("Rust", rust(), "1.55.0"),
];
for (label, stack, version) in stacks {
let report = validate_runtime_version(&stack, version);
eprintln!(
" {} {} — {}",
report.status_label(),
format!("{label} v{version}").bold(),
report.message
);
}
}
}