1. 1//! Banned-token gate (docs/design/68-context-engine.md §9): production
2. 2//! source under `crates/*/src` must never let a vendor name or a topic word
3. 3//! act as a routing key. A `#[cfg(test)]` fixture is allowed to call itself
4. 4//! whatever it likes — the scan stops at the first `#[cfg(test)]` marker in
5. 5//! each file — and a comment does not count as a hard-coding, so `//` and
6. 6//! `///` text is stripped before the remaining lines are checked.
7. 7//!
8. 8//! The banned set is deliberately just the words this codebase's own history
9. 9//! produced: a search vendor's name that once drove tool-name sniffing, and
10. 10//! a topic word from the bug report that motivated deleting it.
11. 11
12. 12use std::path::{Path, PathBuf};
13. 13
14. 14const BANNED_TOKENS: &[&str] = &["tavily", "weather", "noida"];
15. 15
16. 16/// One line the gate refused, already resolved to a workspace-relative path
17. 17/// so the report reads the same regardless of where the suite runs from.
18. 18#[derive(Debug, Clone)]
19. 19pub struct Offense {
20. 20 pub path: String,
21. 21 pub line: usize,
22. 22 pub text: String,
23. 23}
24. 24
25. 25impl std::fmt::Display for Offense {
26. 26 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
27. 27 write!(f, "{}:{}: {}", self.path, self.line, self.text.trim())
28. 28 }
29. 29}
30. 30
31. 31fn workspace_root() -> Result<PathBuf, String> {
32. 32 let manifest_dir = Path::new(env!("CARGO_MANIFEST_DIR"));
33. 33 manifest_dir
34. 34 .parent()
35. 35 .and_then(Path::parent)
36. 36 .map(Path::to_path_buf)
37. 37 .ok_or_else(|| {
38. 38 format!(
39. 39 "{} has no workspace root two levels up",
40. 40 manifest_dir.display()
41. 41 )
42. 42 })
43. 43}
44. 44
45. 45fn collect_rs_files(dir: &Path, out: &mut Vec<PathBuf>) -> Result<(), String> {
46. 46 let entries = std::fs::read_dir(dir).map_err(|error| format!("{}: {error}", dir.display()))?;
47. 47 for entry in entries {
48. 48 let entry = entry.map_err(|error| format!("{}: {error}", dir.display()))?;
49. 49 let path = entry.path();
50. 50 let file_type = entry
51. 51 .file_type()
52. 52 .map_err(|error| format!("{}: {error}", path.display()))?;
53. 53 if file_type.is_dir() {
54. 54 collect_rs_files(&path, out)?;
55. 55 } else if path.extension().is_some_and(|ext| ext == "rs") {
56. 56 out.push(path);
57. 57 }
58. 58 }
59. 59 Ok(())
60. 60}
61. 61
62. 62/// Every `.rs` file under `crates/*/src`, in the workspace named by `root`.
63. 63fn all_src_files(root: &Path) -> Result<Vec<PathBuf>, String> {
64. 64 let mut out = Vec::new();
65. 65 let crates_dir = root.join("crates");
66. 66 let entries = std::fs::read_dir(&crates_dir)
67. 67 .map_err(|error| format!("{}: {error}", crates_dir.display()))?;
68. 68 for entry in entries {
69. 69 let entry = entry.map_err(|error| format!("{}: {error}", crates_dir.display()))?;
70. 70 let src = entry.path().join("src");
71. 71 if src.is_dir() {
72. 72 collect_rs_files(&src, &mut out)?;
73. 73 }
74. 74 }
75. 75 out.sort();
76. 76 Ok(out)
77. 77}
78. 78
79. 79/// Truncates a line at its first `//` that is not inside a string literal,
80. 80/// which covers `///` and `//!` doc comments too (both start with `//`).
81. 81/// Block comments (`/* */`) do not appear in this codebase's `.rs` sources
82. 82/// today, so they are deliberately not handled here.
83. 83fn strip_line_comment(line: &str) -> &str {
84. 84 let bytes = line.as_bytes();
85. 85 let mut quote: Option<u8> = None;
86. 86 let mut i = 0;
87. 87 while i < bytes.len() {
88. 88 let byte = bytes[i];
89. 89 match quote {
90. 90 Some(q) => {
91. 91 if byte == b'\\' {
92. 92 i += 1;
93. 93 } else if byte == q {
94. 94 quote = None;
95. 95 }
96. 96 }
97. 97 None => {
98. 98 if byte == b'"' || byte == b'\'' {
99. 99 quote = Some(byte);
100. 100 } else if byte == b'/' && bytes.get(i + 1) == Some(&b'/') {
101. 101 return &line[..i];
102. 102 }
103. 103 }
104. 104 }
105. 105 i += 1;
106. 106 }
107. 107 line
108. 108}
109. 109
110. 110/// `(1-based line number, comment-stripped text)` for every line before the
111. 111/// file's first `#[cfg(test)]` marker.
112. 112fn production_lines(text: &str) -> Vec<(usize, String)> {
113. 113 let mut out = Vec::new();
114. 114 for (index, raw_line) in text.lines().enumerate() {
115. 115 if raw_line.contains("#[cfg(test)]") {
116. 116 break;
117. 117 }
118. 118 out.push((index + 1, strip_line_comment(raw_line).to_string()));
119. 119 }
120. 120 out
121. 121}
122. 122
123. 123/// Small, explicit exceptions — vocabulary that is presentation vocabulary
124. 124/// or provider-registry data, never a vendor/topic routing key:
125. 125///
126. 126/// * `vak-llm/src/registry.rs` — verified to contain none of the banned
127. 127/// words; allow-listed anyway per the invariant this gate implements.
128. 128/// * `docs/` — out of the walked tree today (only `crates/*/src` is
129. 129/// scanned), kept here so the rule still reads correctly if the walk ever
130. 130/// widens.
131. 131/// * `vak-core/src/presentation_tools.rs`'s `semantic_types` arrays — the
132. 132/// `weather` semantic type is a card shape the runtime still emits
133. 133/// (`emit_metric_card`), not a vendor name.
134. 134/// * `vak-delivery/src/skills.rs`'s registry `provides` list and built-in
135. 135/// recipe id mirror that same `weather` semantic type on the receiving
136. 136/// side; the recipe id is consumed by `vak-agent`'s tests (outside this
137. 137/// agent's scope to rename in the same change).
138. 138fn is_allowed(rel_path: &str, line: &str) -> bool {
139. 139 if rel_path.starts_with("docs/") {
140. 140 return true;
141. 141 }
142. 142 if rel_path == "crates/vak-llm/src/registry.rs" {
143. 143 return true;
144. 144 }
145. 145 if rel_path == "crates/vak-core/src/presentation_tools.rs" && line.contains("semantic_types") {
146. 146 return true;
147. 147 }
148. 148 if rel_path == "crates/vak-delivery/src/skills.rs" {
149. 149 let trimmed = line.trim().trim_end_matches(',');
150. 150 if trimmed == "\"weather\"" || trimmed == "\"weather.forecast\"" {
151. 151 return true;
152. 152 }
153. 153 }
154. 154 false
155. 155}
156. 156
157. 157pub fn scan_banned_tokens() -> Result<Vec<Offense>, String> {
158. 158 let root = workspace_root()?;
159. 159 let mut offenses = Vec::new();
160. 160 for path in all_src_files(&root)? {
161. 161 let rel = path
162. 162 .strip_prefix(&root)
163. 163 .unwrap_or(&path)
164. 164 .to_string_lossy()
165. 165 .replace('\\', "/");
166. 166 let text = std::fs::read_to_string(&path)
167. 167 .map_err(|error| format!("{}: {error}", path.display()))?;
168. 168 for (line, stripped) in production_lines(&text) {
169. 169 let lower = stripped.to_ascii_lowercase();
170. 170 if BANNED_TOKENS.iter().any(|token| lower.contains(token))
171. 171 && !is_allowed(&rel, &stripped)
172. 172 {
173. 173 offenses.push(Offense {
174. 174 path: rel.clone(),
175. 175 line,
176. 176 text: stripped,
177. 177 });
178. 178 }
179. 179 }
180. 180 }
181. 181 Ok(offenses)
182. 182}
183. 183
184. 184#[cfg(test)]
185. 185mod tests {
186. 186 #![allow(clippy::unwrap_used, clippy::expect_used)]
187. 187 use super::*;
188. 188
189. 189 #[test]
190. 190 fn no_vendor_or_topic_routing_keys_in_production_code() {
191. 191 let offenses = scan_banned_tokens().expect("scan crates/*/src");
192. 192 assert!(
193. 193 offenses.is_empty(),
194. 194 "banned tokens found outside tests/comments/allow-list:\n{}",
195. 195 offenses
196. 196 .iter()
197. 197 .map(Offense::to_string)
198. 198 .collect::<Vec<_>>()
199. 199 .join("\n")
200. 200 );
201. 201 }
202. 202}
203. 203