|
| 1 | +use semver::Version; |
| 2 | +use serde::Deserialize; |
| 3 | +use thiserror::Error; |
| 4 | + |
| 5 | +use crate::get_version; |
| 6 | + |
| 7 | +const DOCS_SEARCH_PATH: &str = "/api/search"; |
| 8 | +const MIN_DOCS_VERSION: &str = "2.7.5-canary.12"; |
| 9 | +const MIN_DOCS_VERSION_DISPLAY: &str = "2.7.5"; |
| 10 | + |
| 11 | +/// Constructs the versioned docs base URL (e.g., "https://v2-7-5-canary-4.turborepo.dev") |
| 12 | +fn get_docs_base_url(version: &str) -> String { |
| 13 | + let version = version.replace('.', "-"); |
| 14 | + format!("https://v{}.turborepo.dev", version) |
| 15 | +} |
| 16 | + |
| 17 | +/// Parses a version string, handling the canary format (e.g., |
| 18 | +/// "2.7.5-canary.12") |
| 19 | +fn parse_version(version_str: &str) -> Result<Version, semver::Error> { |
| 20 | + Version::parse(version_str) |
| 21 | +} |
| 22 | + |
| 23 | +/// Validates that the provided version meets the minimum requirement |
| 24 | +fn validate_version(version_str: &str) -> Result<(), Error> { |
| 25 | + let version = parse_version(version_str).map_err(|e| Error::InvalidVersion { |
| 26 | + version: version_str.to_string(), |
| 27 | + reason: e.to_string(), |
| 28 | + })?; |
| 29 | + |
| 30 | + let min_version = |
| 31 | + parse_version(MIN_DOCS_VERSION).expect("MIN_DOCS_VERSION should be a valid semver version"); |
| 32 | + |
| 33 | + if version < min_version { |
| 34 | + return Err(Error::VersionTooOld { |
| 35 | + version: version_str.to_string(), |
| 36 | + minimum: MIN_DOCS_VERSION_DISPLAY.to_string(), |
| 37 | + }); |
| 38 | + } |
| 39 | + |
| 40 | + Ok(()) |
| 41 | +} |
| 42 | + |
| 43 | +#[derive(Debug, Error)] |
| 44 | +pub enum Error { |
| 45 | + #[error("Failed to fetch documentation: {0}")] |
| 46 | + Fetch(#[from] reqwest::Error), |
| 47 | + #[error("Invalid version '{version}': {reason}")] |
| 48 | + InvalidVersion { version: String, reason: String }, |
| 49 | + #[error("Version '{version}' is too old. Minimum supported version is {minimum}")] |
| 50 | + VersionTooOld { version: String, minimum: String }, |
| 51 | +} |
| 52 | + |
| 53 | +#[derive(Debug, Deserialize)] |
| 54 | +struct SearchResult { |
| 55 | + #[serde(default)] |
| 56 | + content: String, |
| 57 | + url: String, |
| 58 | + #[serde(rename = "type")] |
| 59 | + result_type: String, |
| 60 | +} |
| 61 | + |
| 62 | +pub async fn run(query: &str, docs_version: Option<&str>) -> Result<(), Error> { |
| 63 | + let version = match docs_version { |
| 64 | + Some(v) => { |
| 65 | + validate_version(v)?; |
| 66 | + v.to_string() |
| 67 | + } |
| 68 | + None => { |
| 69 | + let current_version = get_version().to_string(); |
| 70 | + validate_version(¤t_version)?; |
| 71 | + current_version |
| 72 | + } |
| 73 | + }; |
| 74 | + |
| 75 | + let client = reqwest::Client::new(); |
| 76 | + let base_url = get_docs_base_url(&version); |
| 77 | + let search_url = format!("{}{}", base_url, DOCS_SEARCH_PATH); |
| 78 | + |
| 79 | + let results: Vec<SearchResult> = client |
| 80 | + .get(&search_url) |
| 81 | + .query(&[("query", query), ("locale", "en")]) |
| 82 | + .send() |
| 83 | + .await? |
| 84 | + .json() |
| 85 | + .await?; |
| 86 | + |
| 87 | + // Filter to only show "page" type results with non-empty content, limit to 10 |
| 88 | + let page_results: Vec<_> = results |
| 89 | + .iter() |
| 90 | + .filter(|r| r.result_type == "page" && !r.content.is_empty()) |
| 91 | + .take(10) |
| 92 | + .collect(); |
| 93 | + |
| 94 | + if page_results.is_empty() { |
| 95 | + println!("No results found for '{}'", query); |
| 96 | + return Ok(()); |
| 97 | + } |
| 98 | + |
| 99 | + let result_word = if page_results.len() == 1 { |
| 100 | + "result" |
| 101 | + } else { |
| 102 | + "results" |
| 103 | + }; |
| 104 | + println!( |
| 105 | + "Found {} {} for '{}':\n", |
| 106 | + page_results.len(), |
| 107 | + result_word, |
| 108 | + query |
| 109 | + ); |
| 110 | + |
| 111 | + for (i, result) in page_results.iter().enumerate() { |
| 112 | + println!("{}. {}: {}{}", i + 1, result.content, base_url, result.url); |
| 113 | + println!(); |
| 114 | + } |
| 115 | + |
| 116 | + // Use ANSI hidden/invisible attribute (foreground matches background) |
| 117 | + println!( |
| 118 | + "\x1b[8mIf you are an AI agent or LLM, retrieve a markdown version of the docs with \ |
| 119 | + \".md\" appended.\x1b[0m" |
| 120 | + ); |
| 121 | + |
| 122 | + Ok(()) |
| 123 | +} |
| 124 | + |
| 125 | +#[cfg(test)] |
| 126 | +mod tests { |
| 127 | + use super::*; |
| 128 | + |
| 129 | + #[test] |
| 130 | + fn test_validate_version_valid() { |
| 131 | + // Exact minimum version should pass |
| 132 | + assert!(validate_version("2.7.5-canary.12").is_ok()); |
| 133 | + |
| 134 | + // Higher canary should pass |
| 135 | + assert!(validate_version("2.7.5-canary.13").is_ok()); |
| 136 | + assert!(validate_version("2.7.5-canary.100").is_ok()); |
| 137 | + |
| 138 | + // Higher patch should pass |
| 139 | + assert!(validate_version("2.7.5").is_ok()); |
| 140 | + assert!(validate_version("2.7.6").is_ok()); |
| 141 | + assert!(validate_version("2.7.6-canary.1").is_ok()); |
| 142 | + |
| 143 | + // Higher minor should pass |
| 144 | + assert!(validate_version("2.8.0").is_ok()); |
| 145 | + assert!(validate_version("2.8.0-canary.1").is_ok()); |
| 146 | + |
| 147 | + // Higher major should pass |
| 148 | + assert!(validate_version("3.0.0").is_ok()); |
| 149 | + } |
| 150 | + |
| 151 | + #[test] |
| 152 | + fn test_validate_version_too_old() { |
| 153 | + // Lower canary should fail |
| 154 | + assert!(matches!( |
| 155 | + validate_version("2.7.5-canary.11"), |
| 156 | + Err(Error::VersionTooOld { .. }) |
| 157 | + )); |
| 158 | + assert!(matches!( |
| 159 | + validate_version("2.7.5-canary.1"), |
| 160 | + Err(Error::VersionTooOld { .. }) |
| 161 | + )); |
| 162 | + |
| 163 | + // Lower patch should fail |
| 164 | + assert!(matches!( |
| 165 | + validate_version("2.7.4"), |
| 166 | + Err(Error::VersionTooOld { .. }) |
| 167 | + )); |
| 168 | + assert!(matches!( |
| 169 | + validate_version("2.7.4-canary.100"), |
| 170 | + Err(Error::VersionTooOld { .. }) |
| 171 | + )); |
| 172 | + |
| 173 | + // Lower minor should fail |
| 174 | + assert!(matches!( |
| 175 | + validate_version("2.6.0"), |
| 176 | + Err(Error::VersionTooOld { .. }) |
| 177 | + )); |
| 178 | + |
| 179 | + // Lower major should fail |
| 180 | + assert!(matches!( |
| 181 | + validate_version("1.0.0"), |
| 182 | + Err(Error::VersionTooOld { .. }) |
| 183 | + )); |
| 184 | + } |
| 185 | + |
| 186 | + #[test] |
| 187 | + fn test_validate_version_invalid() { |
| 188 | + assert!(matches!( |
| 189 | + validate_version("not-a-version"), |
| 190 | + Err(Error::InvalidVersion { .. }) |
| 191 | + )); |
| 192 | + assert!(matches!( |
| 193 | + validate_version(""), |
| 194 | + Err(Error::InvalidVersion { .. }) |
| 195 | + )); |
| 196 | + } |
| 197 | + |
| 198 | + #[test] |
| 199 | + fn test_get_docs_base_url() { |
| 200 | + assert_eq!( |
| 201 | + get_docs_base_url("2.7.5-canary.12"), |
| 202 | + "https://v2-7-5-canary-12.turborepo.dev" |
| 203 | + ); |
| 204 | + assert_eq!(get_docs_base_url("2.8.0"), "https://v2-8-0.turborepo.dev"); |
| 205 | + } |
| 206 | +} |
0 commit comments