1use super::contract::Contract;
17use crate::pulse::model::evidence::{EvidenceKind, EvidencePack};
18use serde::Serialize;
19use std::collections::HashSet;
20use std::sync::LazyLock;
21
22#[derive(Debug, Clone, Copy)]
23pub struct GateConfig {
24 pub min_kept_ratio: f32,
25 pub min_sentences: usize,
26}
27
28impl Default for GateConfig {
29 fn default() -> Self {
30 Self {
31 min_kept_ratio: 0.6,
32 min_sentences: 2,
33 }
34 }
35}
36
37#[derive(Debug, Clone, PartialEq, Serialize)]
38#[serde(tag = "reason", content = "detail", rename_all = "kebab-case")]
39pub enum DropReason {
40 Uncited,
41 UnresolvedIdentifier(String),
43 UngroundedIdentifier(String),
45 NumberMismatch(String),
46 UnsupportedClaim(String),
47}
48
49#[derive(Debug, Clone, PartialEq, Serialize)]
50pub struct KeptSentence {
51 pub text: String,
52 pub cites: Vec<usize>,
54}
55
56#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
57#[serde(rename_all = "kebab-case")]
58pub enum Confidence {
59 High,
60 Medium,
61 Low,
62}
63
64#[derive(Debug, Clone, Default, PartialEq, Serialize)]
65pub struct GateReport {
66 pub slot: String,
67 pub total: usize,
68 pub kept: usize,
69 pub dropped: Vec<(String, DropReason)>,
70 pub rejected: Option<String>,
72}
73
74#[derive(Debug, Clone, PartialEq)]
75pub struct Verified {
76 pub paragraphs: Vec<Vec<KeptSentence>>,
77 pub confidence: Confidence,
78 pub report: GateReport,
79}
80
81#[derive(Debug, Clone, Default)]
84pub struct KnownNames {
85 names: HashSet<String>,
86}
87
88impl KnownNames {
89 pub fn insert(&mut self, name: &str) {
90 let n = name.trim();
91 if n.is_empty() {
92 return;
93 }
94 self.names.insert(n.to_string());
95 for sep in ["::", ".", "/"] {
97 let parts: Vec<&str> = n.split(sep).collect();
98 for i in 1..parts.len() {
99 self.names.insert(parts[i..].join(sep));
100 }
101 }
102 }
103
104 pub fn contains(&self, m: &str) -> bool {
105 let m = m.trim_end_matches("()").trim_end_matches('!');
106 self.names.contains(m)
107 || m.rsplit("::")
108 .next()
109 .is_some_and(|last| self.names.contains(last))
110 }
111}
112
113const PROSE_WORDS: &[&str] = &[
115 "TypeScript",
116 "JavaScript",
117 "GitHub",
118 "GitLab",
119 "PostgreSQL",
120 "MySQL",
121 "SQLite",
122 "WebSocket",
123 "OpenAI",
124 "OpenRouter",
125 "LLMs",
126 "APIs",
127 "JSON",
128 "YAML",
129 "TOML",
130 "HTTP",
131 "HTTPS",
132 "MCP",
133 "CLI",
134 "TUI",
135 "AST",
136 "IDE",
137 "macOS",
138 "iOS",
139 "NodeJS",
140 "README",
141 "CHANGELOG",
142 "e.g",
143 "i.e",
144 "etc",
145];
146
147static BACKTICK: LazyLock<regex::Regex> =
148 LazyLock::new(|| regex::Regex::new(r"`([^`]+)`").expect("valid regex"));
149static CODEISH: LazyLock<regex::Regex> = LazyLock::new(|| {
150 regex::Regex::new(
151 r"(?x)
152 (--[a-z][a-z0-9-]+) # --flag
153 | ([A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)+) # a::b
154 | ([a-z0-9_]+_[a-z0-9_]+) # snake_case
155 | ([A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*)+) # CamelCase
156 | ((?:[\w.-]+/)+[\w.-]+\.[a-z]{1,5}) # path/to/file.ext
157 ",
158 )
159 .expect("valid regex")
160});
161static NUMBER: LazyLock<regex::Regex> =
162 LazyLock::new(|| regex::Regex::new(r"\b\d[\d,]*(?:\.\d+)?\b").expect("valid regex"));
163
164static CLAIMS: LazyLock<Vec<(regex::Regex, &'static str)>> = LazyLock::new(|| {
166 [
167 (r"(?i)\b(http|web|rest|api)\s+server\b|\bhttp api\b|\bweb (app|application|service)\b|\bendpoints?\b", "http-server"),
168 (r"(?i)\bterminal (ui|user interface)\b|\btui\b|\binteractive terminal\b", "tui"),
169 (r"(?i)\bdatabases?\b|\bsqlite\b|\bsql\b", "database"),
170 (r"(?i)\bllms?\b|\blanguage models?\b|\bai providers?\b", "llm"),
171 (r"(?i)\bfile[- ]watch(er|ing)\b|\bwatches (files|the file ?system)\b", "file-watching"),
172 (r"(?i)\bweb (ui|user interface|frontend)\b", "web-ui"),
173 ]
174 .into_iter()
175 .map(|(p, c)| (regex::Regex::new(p).expect("valid regex"), c))
176 .collect()
177});
178
179fn mentions(text: &str) -> Vec<String> {
180 let mut out: Vec<String> = BACKTICK
181 .captures_iter(text)
182 .map(|c| c[1].trim().to_string())
183 .collect();
184 let outside = BACKTICK.replace_all(text, " ");
185 for c in CODEISH.captures_iter(&outside) {
186 let m = c.get(0).unwrap().as_str().trim_end_matches('.');
187 if !PROSE_WORDS.contains(&m) {
188 out.push(m.to_string());
189 }
190 }
191 out.retain(|m| !m.is_empty() && !PROSE_WORDS.contains(&m.as_str()));
192 out
193}
194
195fn norm_number(s: &str) -> String {
196 s.replace(',', "")
197}
198
199fn fact_text(e: &crate::pulse::model::evidence::Evidence) -> String {
200 format!("{}\n{}\n{}", e.subject, e.text, e.names.join("\n"))
201}
202
203fn extra_cites(text: &str, cites: &[usize], pack: &EvidencePack) -> Vec<usize> {
207 let cited_text: String = cites
208 .iter()
209 .filter_map(|&i| pack.items.get(i))
210 .map(fact_text)
211 .collect::<Vec<_>>()
212 .join("\n");
213 let mut extra = Vec::new();
214 for m in mentions(text) {
215 if cited_text.contains(&m) {
216 continue;
217 }
218 if let Some(i) = pack
219 .items
220 .iter()
221 .position(|e| e.names.iter().any(|n| n == &m) || e.subject == m)
222 && !cites.contains(&i)
223 && !extra.contains(&i)
224 {
225 extra.push(i);
226 }
227 }
228 extra
229}
230
231fn check(
233 text: &str,
234 cites: &[usize],
235 pack: &EvidencePack,
236 known: &KnownNames,
237) -> Option<DropReason> {
238 if cites.is_empty() {
239 return Some(DropReason::Uncited);
240 }
241 let cited: Vec<_> = cites.iter().filter_map(|&i| pack.items.get(i)).collect();
242 let cited_text: String = cited
243 .iter()
244 .map(|e| format!("{}\n{}\n{}", e.subject, e.text, e.names.join("\n")))
245 .collect::<Vec<_>>()
246 .join("\n");
247
248 for m in mentions(text) {
249 let head = m.split_whitespace().next().unwrap_or(&m).to_string();
251 if !known.contains(&m) && !known.contains(&head) && !cited_text.contains(&m) {
252 return Some(DropReason::UnresolvedIdentifier(m));
253 }
254 let grounded = cited_text.contains(&m)
255 || cited_text.contains(&head)
256 || m.rsplit("::")
257 .next()
258 .is_some_and(|last| cited_text.contains(last))
259 || m.rsplit('/')
260 .next()
261 .is_some_and(|last| cited_text.contains(last));
262 if !grounded {
263 return Some(DropReason::UngroundedIdentifier(m));
264 }
265 }
266
267 let cited_numbers: HashSet<String> = NUMBER
268 .find_iter(&cited_text)
269 .map(|n| norm_number(n.as_str()))
270 .collect();
271 for n in NUMBER.find_iter(&BACKTICK.replace_all(text, " ")) {
272 let v = norm_number(n.as_str());
273 if v.len() >= 2 && !cited_numbers.contains(&v) {
274 return Some(DropReason::NumberMismatch(n.as_str().to_string()));
275 }
276 }
277
278 for (re, cap) in CLAIMS.iter() {
279 if let Some(m) = re.find(text) {
280 let phrase = m.as_str().to_ascii_lowercase();
281 let backed = cited.iter().any(|e| {
282 e.capability.as_deref() == Some(*cap)
283 || (matches!(
284 e.kind,
285 EvidenceKind::DocSection
286 | EvidenceKind::ModuleDoc
287 | EvidenceKind::Item
288 | EvidenceKind::Command
289 ) && e.text.to_ascii_lowercase().contains(&phrase))
290 });
291 if !backed {
292 return Some(DropReason::UnsupportedClaim(m.as_str().to_string()));
293 }
294 }
295 }
296 None
297}
298
299fn split_sentences(text: &str) -> Vec<String> {
301 let mut out = Vec::new();
302 let mut cur = String::new();
303 let mut in_tick = false;
304 let chars: Vec<char> = text.chars().collect();
305 for (i, &c) in chars.iter().enumerate() {
306 cur.push(c);
307 if c == '`' {
308 in_tick = !in_tick;
309 }
310 let end = matches!(c, '.' | '!' | '?')
311 && !in_tick
312 && chars.get(i + 1) == Some(&' ')
313 && chars.get(i + 2).is_some_and(|n| n.is_uppercase());
314 if end {
315 out.push(cur.trim().to_string());
316 cur.clear();
317 }
318 }
319 if !cur.trim().is_empty() {
320 out.push(cur.trim().to_string());
321 }
322 out
323}
324
325pub fn verify(
327 contract: &Contract,
328 pack: &EvidencePack,
329 known: &KnownNames,
330 cfg: &GateConfig,
331) -> Result<Verified, GateReport> {
332 let mut report = GateReport {
333 slot: pack.slot.clone(),
334 ..GateReport::default()
335 };
336 if contract.status != "ok" {
337 report.rejected = Some(format!(
338 "insufficient evidence: {}",
339 contract.missing.join("; ")
340 ));
341 return Err(report);
342 }
343 let mut paragraphs = Vec::new();
344 for p in &contract.paragraphs {
345 let mut kept = Vec::new();
346 let mut total = 0;
347 for s in &p.sentences {
348 let cites: Vec<usize> = s
349 .cite
350 .iter()
351 .filter_map(|h| {
352 let n: usize = h.trim().trim_start_matches('F').parse().ok()?;
353 (n >= 1 && n <= pack.items.len()).then_some(n - 1)
354 })
355 .take(3)
356 .collect();
357 for piece in split_sentences(&s.text) {
358 total += 1;
359 report.total += 1;
360 let mut cites = cites.clone();
361 if !cites.is_empty() {
362 cites.extend(extra_cites(&piece, &cites, pack));
363 }
364 match check(&piece, &cites, pack, known) {
365 None => kept.push(KeptSentence { text: piece, cites }),
366 Some(r) => report.dropped.push((piece, r)),
367 }
368 }
369 }
370 if total > 0 && kept.len() * 2 >= total {
371 report.kept += kept.len();
372 paragraphs.push(kept);
373 } else {
374 for k in kept {
376 report.dropped.push((k.text, DropReason::Uncited));
377 }
378 }
379 }
380 let ratio = if report.total == 0 {
381 0.0
382 } else {
383 report.kept as f32 / report.total as f32
384 };
385 if report.kept < cfg.min_sentences || ratio < cfg.min_kept_ratio {
386 report.rejected = Some(format!(
387 "kept {} of {} sentences (need {} and {:.0}%)",
388 report.kept,
389 report.total,
390 cfg.min_sentences,
391 cfg.min_kept_ratio * 100.0
392 ));
393 return Err(report);
394 }
395 let g = pack.groundability();
396 let confidence = if ratio >= 0.9 && g >= 0.5 {
397 Confidence::High
398 } else if ratio < 0.75 || g < 0.3 {
399 Confidence::Low
400 } else {
401 Confidence::Medium
402 };
403 Ok(Verified {
404 paragraphs,
405 confidence,
406 report,
407 })
408}
409
410#[cfg(test)]
411mod tests {
412 use super::*;
413 use crate::pulse::model::evidence::Evidence;
414 use crate::pulse::write::contract::{Paragraph, Sentence};
415
416 fn ev(kind: EvidenceKind, text: &str, names: &[&str], cap: Option<&str>) -> Evidence {
417 Evidence {
418 id: text.into(),
419 kind,
420 subject: "src/interactive".into(),
421 text: text.into(),
422 names: names.iter().map(|s| s.to_string()).collect(),
423 source: None,
424 capability: cap.map(str::to_string),
425 }
426 }
427
428 fn pack() -> EvidencePack {
429 let mut p = EvidencePack::new("module:src/interactive", "the module src/interactive");
430 p.push(ev(EvidenceKind::Metric, "files=12 lines=4,210", &[], None));
431 p.push(ev(
432 EvidenceKind::Capability,
433 "terminal user interface (imports `ratatui` in src/interactive/app.rs:5)",
434 &["ratatui"],
435 Some("tui"),
436 ));
437 p.push(ev(
438 EvidenceKind::Item,
439 "pub struct InteractiveApp — Interactive search session state",
440 &["InteractiveApp"],
441 None,
442 ));
443 p
444 }
445
446 fn known() -> KnownNames {
447 let mut k = KnownNames::default();
448 for n in [
449 "reflex::interactive::InteractiveApp",
450 "src/interactive",
451 "src/interactive/app.rs",
452 "ratatui",
453 "reflex::cache::CacheManager",
454 ] {
455 k.insert(n);
456 }
457 k
458 }
459
460 fn contract(sents: &[(&str, &[&str])]) -> Contract {
461 Contract {
462 status: "ok".into(),
463 missing: vec![],
464 paragraphs: vec![Paragraph {
465 sentences: sents
466 .iter()
467 .map(|(t, c)| Sentence {
468 text: t.to_string(),
469 cite: c.iter().map(|s| s.to_string()).collect(),
470 })
471 .collect(),
472 }],
473 }
474 }
475
476 fn reasons(c: &Contract) -> Vec<DropReason> {
477 match verify(
478 c,
479 &pack(),
480 &known(),
481 &GateConfig {
482 min_kept_ratio: 0.0,
483 min_sentences: 0,
484 },
485 ) {
486 Ok(v) => v.report.dropped.into_iter().map(|(_, r)| r).collect(),
487 Err(r) => r.dropped.into_iter().map(|(_, r)| r).collect(),
488 }
489 }
490
491 #[test]
492 fn grounded_sentences_pass() {
493 let c = contract(&[
494 (
495 "The module renders an interactive terminal UI with `ratatui`.",
496 &["F2"],
497 ),
498 (
499 "`InteractiveApp` holds the session state across 12 files.",
500 &["F3", "F1"],
501 ),
502 ]);
503 let v = verify(&c, &pack(), &known(), &GateConfig::default()).unwrap();
504 assert_eq!(v.report.kept, 2, "{:?}", v.report.dropped);
505 }
506
507 #[test]
508 fn the_http_server_regression_is_blocked() {
509 let c = contract(&[("This module provides an HTTP server for search.", &["F3"])]);
511 assert_eq!(
512 reasons(&c),
513 vec![DropReason::UnsupportedClaim("HTTP server".into())]
514 );
515 }
516
517 #[test]
518 fn each_drop_reason() {
519 assert_eq!(
520 reasons(&contract(&[("It renders things.", &[])])),
521 vec![DropReason::Uncited]
522 );
523 assert_eq!(
524 reasons(&contract(&[("It uses `FooBarBaz` internally.", &["F3"])])),
525 vec![DropReason::UnresolvedIdentifier("FooBarBaz".into())]
526 );
527 assert_eq!(
528 reasons(&contract(&[(
529 "It wraps `CacheManager` for storage.",
530 &["F3"]
531 )])),
532 vec![DropReason::UngroundedIdentifier("CacheManager".into())]
533 );
534 assert_eq!(
535 reasons(&contract(&[("It spans 40 files.", &["F1"])])),
536 vec![DropReason::NumberMismatch("40".into())]
537 );
538 assert_eq!(
539 reasons(&contract(&[("It has 4210 lines.", &["F1"])])).len(),
540 0,
541 "4,210 and 4210 are the same number"
542 );
543 }
544
545 #[test]
546 fn a_name_from_another_fact_of_the_pack_is_cited_automatically() {
547 let c = contract(&[(
549 "`InteractiveApp` holds the session state across 12 files.",
550 &["F1"],
551 )]);
552 let v = verify(
553 &c,
554 &pack(),
555 &known(),
556 &GateConfig {
557 min_kept_ratio: 0.0,
558 min_sentences: 0,
559 },
560 )
561 .unwrap();
562 assert_eq!(v.report.kept, 1, "{:?}", v.report.dropped);
563 assert_eq!(v.paragraphs[0][0].cites, vec![0, 2]);
564 }
565
566 #[test]
567 fn bad_sections_are_rejected() {
568 let c = contract(&[
569 ("It uses `Nope`.", &["F3"]),
570 ("It spans 99 files.", &["F1"]),
571 ]);
572 let r = verify(&c, &pack(), &known(), &GateConfig::default()).unwrap_err();
573 assert!(r.rejected.is_some());
574 let insufficient = Contract {
575 status: "insufficient_evidence".into(),
576 missing: vec!["what the module does".into()],
577 paragraphs: vec![],
578 };
579 let r = verify(&insufficient, &pack(), &known(), &GateConfig::default()).unwrap_err();
580 assert!(r.rejected.unwrap().contains("what the module does"));
581 }
582
583 #[test]
584 fn run_on_sentences_are_split() {
585 assert_eq!(
586 split_sentences("It parses code. It caches symbols in `a.b`. Done"),
587 vec!["It parses code.", "It caches symbols in `a.b`.", "Done"]
588 );
589 }
590
591 #[test]
592 fn mentions_find_code_shapes() {
593 let m = mentions(
594 "Run `rfx index` with --force; see src/cache.rs and the QueryEngine or query_engine, not TypeScript.",
595 );
596 assert!(m.contains(&"rfx index".to_string()));
597 assert!(m.contains(&"--force".to_string()));
598 assert!(m.contains(&"src/cache.rs".to_string()));
599 assert!(m.contains(&"QueryEngine".to_string()));
600 assert!(m.contains(&"query_engine".to_string()));
601 assert!(!m.contains(&"TypeScript".to_string()));
602 }
603}