Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_text/src/lint/mutable.rs

38.3 KiB, 1 run

created by r1870400018:75231, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! The mutable-literal gate (D-20261026-02): finds hard-coded data that a second deployment of the
2//! same build could rightly want different (locations, hosts, model ids, timings, limits), so that
3//! it moves to config.
4//!
5//! Strings and comments are tokens from `fmt::lex`, never regex guesses. Three things are flagged:
6//! a string literal shaped like a path, URL, host, address or model id; a `const` or `static` whose
7//! name is in the mutable vocabulary and whose value holds a literal; and a timing call with a
8//! literal argument (`Duration::from_secs(30)`, `sleep(30)`, `setTimeout(f, 30)`). Bare numerals in
9//! expressions are never flagged.
10//!
11//! Exempt: comments, the arguments of message macros, `#[cfg(test)]` and `#[test]` items, the body
12//! of `impl Default` for a config type (the one sanctioned home of a default), and anything marked
13//! `// fixed: <why>`, trailing on its line or as a banner over a group that ends at the first
14//! blank line. A why of fewer than two words is itself a failure.
15//!
16//! A ratchet `Baseline` lists the debt that exists: a hit beyond it fails, and so does an entry no
17//! longer found, so the baseline only shrinks. Entries are keyed by file, class and token text,
18//! never by line, so edits elsewhere do not churn it.
19
20use crate::fmt::{
21 cst::{
22 Token,
23 TokenKind,
24 Trivia,
25 },
26 lex::{
27 js_tokens,
28 lex,
29 rust_tokens,
30 },
31};
32
33use oxedyne_fe2o3_core::prelude::*;
34
35use std::{
36 collections::{
37 BTreeMap,
38 BTreeSet,
39 },
40 fmt,
41 fs,
42 path::Path,
43};
44
45
46/// Source language of a scanned file.
47#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
48pub enum Lang {
49 Rust,
50 Js,
51}
52
53impl Lang {
54 /// The language of a file, by extension, or `None` when it is not scanned.
55 pub fn of(path: &Path) -> Option<Self> {
56 match path.extension().and_then(|e| e.to_str()) {
57 Some("rs") => Some(Self::Rust),
58 Some("js") | Some("mjs") => Some(Self::Js),
59 _ => None,
60 }
61 }
62}
63
64/// What kind of mutable datum a hit is.
65#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
66pub enum Class {
67 Path, // A file location.
68 Host, // A URL, host, address or `host:port`.
69 Model, // A model id.
70 Named, // A `const` or `static` named in the mutable vocabulary.
71 Timing, // A timing call with a literal argument.
72}
73
74impl Class {
75 pub fn name(&self) -> &'static str {
76 match self {
77 Self::Path => "path",
78 Self::Host => "host",
79 Self::Model => "model",
80 Self::Named => "named",
81 Self::Timing => "timing",
82 }
83 }
84
85 pub fn from_name(s: &str) -> Outcome<Self> {
86 match s {
87 "path" => Ok(Self::Path),
88 "host" => Ok(Self::Host),
89 "model" => Ok(Self::Model),
90 "named" => Ok(Self::Named),
91 "timing" => Ok(Self::Timing),
92 _ => Err(err!("Unknown mutable-literal class '{}'.", s; Invalid, Input)),
93 }
94 }
95}
96
97impl fmt::Display for Class {
98 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
99 write!(f, "{}", self.name())
100 }
101}
102
103/// One flagged literal. `file` is relative to the scanned root, with `/` separators.
104#[derive(Clone, Debug, Eq, PartialEq)]
105pub struct Hit {
106 pub file: String,
107 pub line: usize,
108 pub class: Class,
109 pub text: String, // Normalised token text, the baseline key.
110}
111
112impl Hit {
113 pub fn key(&self) -> Key {
114 Key { file: self.file.clone(), class: self.class, text: self.text.clone() }
115 }
116}
117
118impl fmt::Display for Hit {
119 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
120 write!(f, "{}:{}: {}: {}", self.file, self.line, self.class, self.text)
121 }
122}
123
124/// The line-independent identity of a hit.
125#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
126pub struct Key {
127 pub file: String,
128 pub class: Class,
129 pub text: String,
130}
131
132impl fmt::Display for Key {
133 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
134 write!(f, "{}: {}: {}", self.file, self.class, self.text)
135 }
136}
137
138/// A permanent exception that cannot carry a `// fixed:` comment (generated code, embedded data).
139/// A `text` of `*` covers every hit of the class in the file.
140#[derive(Clone, Debug, Eq, PartialEq)]
141pub struct Allow {
142 pub file: String,
143 pub class: Class,
144 pub text: String,
145 pub why: String,
146}
147
148impl Allow {
149 pub fn key(&self) -> Key {
150 Key { file: self.file.clone(), class: self.class, text: self.text.clone() }
151 }
152
153 /// Does this exception cover the key?
154 pub fn covers(&self, key: &Key) -> bool {
155 self.file == key.file && self.class == key.class && (self.text == "*" || self.text == key.text)
156 }
157}
158
159/// The ratchet: the debt that exists, as a count per key, and the permanent exceptions.
160#[derive(Clone, Debug, Default, Eq, PartialEq)]
161pub struct Baseline {
162 pub entries: BTreeMap<Key, usize>,
163 pub allow: Vec<Allow>,
164}
165
166impl Baseline {
167 pub fn from_hits(hits: &[Hit]) -> Self {
168 let mut base = Self::default();
169 for h in hits {
170 *base.entries.entry(h.key()).or_insert(0) += 1;
171 }
172 base
173 }
174
175 /// A baseline of the given hits that keeps this one's allow list, dropping entries the allow
176 /// list already covers.
177 pub fn regenerate(&self, hits: &[Hit]) -> Self {
178 let kept: Vec<Hit> = hits.iter()
179 .filter(|h| { let k = h.key(); !self.allow.iter().any(|a| a.covers(&k)) })
180 .cloned().collect();
181 let mut base = Self::from_hits(&kept);
182 base.allow = self.allow.clone();
183 base
184 }
185}
186
187/// A `// fixed:` marker whose why is too thin to name a standard, format or identity.
188#[derive(Clone, Debug, Eq, PartialEq)]
189pub struct Marker {
190 pub file: String,
191 pub line: usize,
192 pub why: String,
193}
194
195/// The hits of one source, and its thin `// fixed:` markers.
196#[derive(Clone, Debug, Default)]
197pub struct Scan {
198 pub hits: Vec<Hit>,
199 pub bad_fixed: Vec<Marker>,
200}
201
202/// The verdict of a tree against its baseline.
203#[derive(Clone, Debug, Default)]
204pub struct Report {
205 pub new: Vec<Hit>, // Hits beyond the baseline count for their key.
206 pub stale: Vec<Key>, // Baseline entries with fewer hits than their count.
207 pub bad_fixed: Vec<Marker>,// `// fixed:` markers with a why under two words.
208 pub bad_allow: Vec<Allow>, // Allow entries with an empty why.
209 pub files: usize, // Files scanned.
210}
211
212impl Report {
213 pub fn is_clean(&self) -> bool {
214 self.new.is_empty()
215 && self.stale.is_empty()
216 && self.bad_fixed.is_empty()
217 && self.bad_allow.is_empty()
218 }
219}
220
221impl fmt::Display for Report {
222 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
223 if self.is_clean() {
224 return write!(f, "No new mutable literals in {} files.", self.files);
225 }
226 if !self.new.is_empty() {
227 writeln!(f, "{} new mutable literal(s); move each to config, or mark it \
228 `// fixed: <why>` when a protocol, format or identity fixes it:", self.new.len())?;
229 for h in &self.new {
230 writeln!(f, " {}", h)?;
231 }
232 }
233 if !self.stale.is_empty() {
234 writeln!(f, "{} stale baseline entr(y/ies); delete them from the baseline in this \
235 commit:", self.stale.len())?;
236 for k in &self.stale {
237 writeln!(f, " {}", k)?;
238 }
239 }
240 if !self.bad_fixed.is_empty() {
241 writeln!(f, "{} `// fixed:` marker(s) without a why naming the standard, format or \
242 identity:", self.bad_fixed.len())?;
243 for h in &self.bad_fixed {
244 writeln!(f, " {}:{}", h.file, h.line)?;
245 }
246 }
247 if !self.bad_allow.is_empty() {
248 writeln!(f, "{} allow entr(y/ies) with an empty why:", self.bad_allow.len())?;
249 for a in &self.bad_allow {
250 writeln!(f, " {}", a.key())?;
251 }
252 }
253 Ok(())
254 }
255}
256
257/// Compares the hits of a tree with its baseline.
258pub fn check(hits: &[Hit], bad_fixed: &[Marker], base: &Baseline) -> Report {
259 let mut rep = Report::default();
260 rep.bad_fixed = bad_fixed.to_vec();
261 let mut allowed = Vec::new();
262 for a in &base.allow {
263 if a.why.trim().is_empty() {
264 rep.bad_allow.push(a.clone());
265 } else {
266 allowed.push(a);
267 }
268 }
269 let mut seen: BTreeMap<Key, usize> = BTreeMap::new();
270 for h in hits {
271 let key = h.key();
272 if allowed.iter().any(|a| a.covers(&key)) {
273 continue;
274 }
275 let n = seen.entry(key.clone()).or_insert(0);
276 *n += 1;
277 let limit = base.entries.get(&key).copied().unwrap_or(0);
278 if *n > limit {
279 rep.new.push(h.clone());
280 }
281 }
282 for (key, count) in &base.entries {
283 if seen.get(key).copied().unwrap_or(0) < *count {
284 rep.stale.push(key.clone());
285 }
286 }
287 rep
288}
289
290/// Scans every `.rs` and `.js` source under `root`, skipping build output, version-control
291/// metadata and the `tests/`, `benches/` and `examples/` trees.
292pub fn scan_tree(root: &Path) -> Outcome<(Scan, usize)> {
293 let mut files = Vec::new();
294 res!(collect(root, root, &mut files));
295 files.sort();
296 let mut all = Scan::default();
297 for (rel, path, lang) in &files {
298 let src = match fs::read_to_string(path) {
299 Ok(s) => s,
300 Err(e) => return Err(err!(e, "While reading source {}.", path.display(); IO, File, Read)),
301 };
302 let scan = res!(scan(&src, *lang, rel));
303 all.hits.extend(scan.hits);
304 all.bad_fixed.extend(scan.bad_fixed);
305 }
306 Ok((all, files.len()))
307}
308
309/// Scans the tree under `root` and checks it against `base`.
310pub fn check_tree(root: &Path, base: &Baseline) -> Outcome<Report> {
311 let (scan, files) = res!(scan_tree(root));
312 let mut rep = check(&scan.hits, &scan.bad_fixed, base);
313 rep.files = files;
314 Ok(rep)
315}
316
317// fixed: build output, metadata and test-only trees, the gate's own scope rule.
318const SKIP_DIRS: [&str; 8] = ["target", "tests", "benches", "examples", "node_modules", ".git", ".ore", "test"];
319
320fn collect(root: &Path, dir: &Path, out: &mut Vec<(String, std::path::PathBuf, Lang)>) -> Outcome<()> {
321 let rd = match fs::read_dir(dir) {
322 Ok(rd) => rd,
323 Err(e) => return Err(err!(e, "While listing {}.", dir.display(); IO, File, Read)),
324 };
325 for entry in rd {
326 let entry = res!(entry);
327 let path = entry.path();
328 let name = entry.file_name().to_string_lossy().to_string();
329 let ft = res!(entry.file_type());
330 if ft.is_dir() {
331 if !SKIP_DIRS.contains(&name.as_str()) {
332 res!(collect(root, &path, out));
333 }
334 continue;
335 }
336 if !ft.is_file() || name.ends_with("_tests.rs") || name == "tests.rs" || name.ends_with(".min.js") {
337 continue;
338 }
339 if let Some(lang) = Lang::of(&path) {
340 let rel = match path.strip_prefix(root) {
341 Ok(r) => r.to_string_lossy().replace('\\', "/"),
342 Err(_) => path.to_string_lossy().to_string(),
343 };
344 out.push((rel, path, lang));
345 }
346 }
347 Ok(())
348}
349
350// Message macros, whose string arguments are messages rather than data, and compile-time includes.
351// fixed: the names of std and fe2o3_core macros.
352const MESSAGE_MACROS: [&str; 26] = [
353 "err", "info", "warn", "error", "debug", "trace", "test", "println", "eprintln", "print",
354 "eprint", "panic", "assert", "assert_eq", "assert_ne", "debug_assert", "debug_assert_eq",
355 "debug_assert_ne", "unreachable", "todo", "unimplemented", "include_str", "include_bytes",
356 "include", "env", "option_env",
357];
358
359// fixed: the console and error methods of the JavaScript standard library.
360const JS_MESSAGE_CALLS: [&str; 6] = ["log", "warn", "error", "info", "debug", "trace"];
361
362/// Scans one source. `file` is the name recorded in each hit.
363pub fn scan(src: &str, lang: Lang, file: &str) -> Outcome<Scan> {
364 let toks = match lang {
365 Lang::Rust => res!(lex(src, &rust_tokens())),
366 Lang::Js => res!(lex(src, &js_tokens())),
367 };
368 let lines = LineIndex::new(src);
369 let mut out = Scan::default();
370 let fixed = fixed_lines(src, &toks, &lines, file, &mut out.bad_fixed);
371 let skip = skipped(&toks, lang);
372 let waits = numeric_consts(&toks, lang, &lines, &fixed, &skip);
373
374 let mut i = 0;
375 while i < toks.len() {
376 if skip[i] {
377 i += 1;
378 continue;
379 }
380 let line = lines.line_of(toks[i].span.start);
381 let covered = fixed.contains(&line);
382 // A const or static item.
383 if let Some((name, end, literal)) = const_item(&toks, i, lang) {
384 if is_mutable_name(&name) && literal {
385 if !covered {
386 out.hits.push(Hit { file: file.to_string(), line, class: Class::Named, text: name });
387 }
388 i = end;
389 continue;
390 }
391 }
392 if let Some((text, end)) = timing_call(&toks, i, lang, &waits) {
393 if !covered {
394 out.hits.push(Hit { file: file.to_string(), line, class: Class::Timing, text });
395 }
396 i = end;
397 continue;
398 }
399 // A string, folded with the literal pieces joined to it by `concat!` or `+`, so that a
400 // value split across pieces is classified whole. The hit is on the first piece's line.
401 let folded = match concat_macro(&toks, i, lang) {
402 Some(f) => Some(f),
403 None if toks[i].kind == TokenKind::StringLit
404 && !(lang == Lang::Js && is_module_specifier(&toks, i)) => Some(plus_chain(&toks, i, &skip)),
405 None => None,
406 };
407 if let Some((text, end)) = folded {
408 if let Some(class) = classify(&text) {
409 if !covered {
410 out.hits.push(Hit { file: file.to_string(), line, class, text });
411 }
412 }
413 i = end;
414 continue;
415 }
416 i += 1;
417 }
418 Ok(out)
419}
420
421struct LineIndex {
422 starts: Vec<usize>,
423}
424
425impl LineIndex {
426 fn new(src: &str) -> Self {
427 let mut starts = vec![0];
428 for (i, b) in src.bytes().enumerate() {
429 if b == b'\n' {
430 starts.push(i + 1);
431 }
432 }
433 Self { starts }
434 }
435
436 /// The 1-based line holding byte `pos`.
437 fn line_of(&self, pos: usize) -> usize {
438 match self.starts.binary_search(&pos) {
439 Ok(i) => i + 1,
440 Err(i) => i,
441 }
442 }
443}
444
445/// The lines covered by a `// fixed:` marker, trailing on its line or as a banner over the lines
446/// that follow it up to the first blank line. Thin markers still cover, and are reported.
447fn fixed_lines(
448 src: &str,
449 toks: &[Token],
450 lines: &LineIndex,
451 file: &str,
452 bad: &mut Vec<Marker>,
453)
454 -> BTreeSet<usize>
455{
456 let blank: Vec<bool> = src.split('\n').map(|l| l.trim().is_empty()).collect();
457 let mut covered = BTreeSet::new();
458 let mut prev_end: Option<usize> = None;
459 for tok in toks {
460 let mut line = match prev_end {
461 Some(e) => lines.line_of(e.saturating_sub(1)),
462 None => 1,
463 };
464 let mut has_code = prev_end.is_some();
465 for t in &tok.leading_trivia {
466 match t {
467 Trivia::Newline => { line += 1; has_code = false; }
468 Trivia::Whitespace(_) => {}
469 Trivia::BlockComment(c) => { line += c.matches('\n').count(); }
470 Trivia::LineComment(c) => {
471 let body = c.trim_start_matches('/').trim();
472 if let Some(why) = body.strip_prefix("fixed:") {
473 let why = why.trim();
474 if why.split_whitespace().count() < 2 {
475 bad.push(Marker { file: file.to_string(), line, why: why.to_string() });
476 }
477 if has_code {
478 covered.insert(line);
479 } else {
480 let mut l = line + 1;
481 while l <= blank.len() && !blank[l - 1] {
482 covered.insert(l);
483 l += 1;
484 }
485 }
486 }
487 }
488 }
489 }
490 prev_end = Some(tok.span.end);
491 }
492 covered
493}
494
495fn is_punct(t: &Token, c: char) -> bool {
496 t.kind == TokenKind::Punct(c)
497}
498
499fn is_ident(t: &Token, s: &str) -> bool {
500 t.kind == TokenKind::Ident && t.text == s
501}
502
503fn is_keyword(t: &Token, s: &str) -> bool {
504 matches!(&t.kind, TokenKind::Keyword(k) if k == s)
505}
506
507/// The index just past the group that opens at `open`, or the end of the tokens.
508fn group_end(toks: &[Token], open: usize) -> usize {
509 let mut depth = 0isize;
510 let mut i = open;
511 while i < toks.len() {
512 match toks[i].kind {
513 TokenKind::Punct('(') | TokenKind::Punct('[') | TokenKind::Punct('{') => depth += 1,
514 TokenKind::Punct(')') | TokenKind::Punct(']') | TokenKind::Punct('}') => {
515 depth -= 1;
516 if depth <= 0 {
517 return i + 1;
518 }
519 }
520 _ => {}
521 }
522 i += 1;
523 }
524 toks.len()
525}
526
527/// The index just past the item that starts at `i`: its first depth-0 `;`, or the close of its
528/// first brace block.
529fn item_end(toks: &[Token], mut i: usize) -> usize {
530 while i < toks.len() && toks[i].kind == TokenKind::Attribute {
531 i += 1;
532 }
533 while i < toks.len() {
534 match toks[i].kind {
535 TokenKind::Punct(';') => return i + 1,
536 TokenKind::Punct('{') => return group_end(toks, i),
537 TokenKind::Punct('(') | TokenKind::Punct('[') => i = group_end(toks, i),
538 _ => i += 1,
539 }
540 }
541 toks.len()
542}
543
544/// Marks the tokens no rule looks at: test items, message macro arguments, and the `Default` of
545/// a config type.
546fn skipped(toks: &[Token], lang: Lang) -> Vec<bool> {
547 let mut skip = vec![false; toks.len()];
548 let configs = config_types(toks);
549 let mut i = 0;
550 while i < toks.len() {
551 let t = &toks[i];
552 let mut span: Option<(usize, usize)> = None;
553 if t.kind == TokenKind::Attribute {
554 let a: String = t.text.chars().filter(|c| !c.is_whitespace()).collect();
555 if a == "#[test]" || a.starts_with("#[cfg(test") || a.contains("::test]")
556 || a.starts_with("#[cfg(all(test") || a.starts_with("#[cfg(any(test")
557 {
558 span = Some((i, item_end(toks, i + 1)));
559 }
560 } else if t.kind == TokenKind::Ident && i + 2 < toks.len() && is_punct(&toks[i + 1], '!')
561 && MESSAGE_MACROS.contains(&t.text.as_str())
562 && matches!(toks[i + 2].kind,
563 TokenKind::Punct('(') | TokenKind::Punct('[') | TokenKind::Punct('{'))
564 {
565 span = Some((i, group_end(toks, i + 2)));
566 } else if lang == Lang::Js && is_ident(t, "console") {
567 // `console.log(…)`.
568 if i + 3 < toks.len() && is_punct(&toks[i + 1], '.')
569 && JS_MESSAGE_CALLS.contains(&toks[i + 2].text.as_str()) && is_punct(&toks[i + 3], '(')
570 {
571 span = Some((i, group_end(toks, i + 3)));
572 }
573 } else if lang == Lang::Js && is_keyword(t, "throw") {
574 // `throw [new] X(…)`, where `(` is reached within the statement: `throw e;` is not a call.
575 if let Some(j) = throw_call_open(toks, i) {
576 span = Some((i, group_end(toks, j)));
577 }
578 } else if lang == Lang::Rust && is_keyword(t, "impl") {
579 // `impl Default for T {…}` where T is a config type.
580 let mut j = i + 1;
581 if j < toks.len() && is_punct(&toks[j], '<') {
582 while j < toks.len() && !is_punct(&toks[j], '>') {
583 j += 1;
584 }
585 j += 1;
586 }
587 if j + 2 < toks.len() && is_ident(&toks[j], "Default") && is_keyword(&toks[j + 1], "for")
588 && configs.contains(&toks[j + 2].text)
589 {
590 span = Some((i, item_end(toks, j)));
591 }
592 }
593 match span {
594 Some((a, b)) => {
595 for k in a..b.min(toks.len()) {
596 skip[k] = true;
597 }
598 i = b.max(i + 1);
599 }
600 None => i += 1,
601 }
602 }
603 skip
604}
605
606/// The `(` of the error constructor in `throw [new] X.Y(…)` at `i`, if the statement is that call.
607/// The walk stops at `;`, `}` or a token that starts a new line, so it never leaves the statement.
608fn throw_call_open(toks: &[Token], i: usize) -> Option<usize> {
609 let mut j = i + 1;
610 if toks.get(j).map_or(false, |t| is_keyword(t, "new") || is_ident(t, "new")) {
611 j += 1;
612 }
613 let mut want_name = true;
614 while j < toks.len() {
615 let t = &toks[j];
616 if t.leading_trivia.iter().any(|v| matches!(v, Trivia::Newline)) {
617 return None;
618 }
619 match t.kind {
620 TokenKind::Ident if want_name => want_name = false,
621 TokenKind::Punct('.') if !want_name => want_name = true,
622 TokenKind::Punct('(') if !want_name => return Some(j),
623 _ => return None,
624 }
625 j += 1;
626 }
627 None
628}
629
630/// The types in this source that are config types: derive `FromDatMap`, or implement `Config`.
631fn config_types(toks: &[Token]) -> BTreeSet<String> {
632 let mut out = BTreeSet::new();
633 let mut pending = false;
634 for (i, t) in toks.iter().enumerate() {
635 if t.kind == TokenKind::Attribute && t.text.contains("FromDatMap") {
636 pending = true;
637 } else if pending && (is_keyword(t, "struct") || is_keyword(t, "enum")) {
638 if let Some(n) = toks.get(i + 1) {
639 out.insert(n.text.clone());
640 }
641 pending = false;
642 } else if is_keyword(t, "impl") {
643 // `impl Config for T` or `impl cfg::Config for T`.
644 let mut j = i + 1;
645 while j < toks.len() && j < i + 6 && !is_keyword(&toks[j], "for") {
646 j += 1;
647 }
648 if j + 1 < toks.len() && j > i + 1 && is_ident(&toks[j - 1], "Config") {
649 out.insert(toks[j + 1].text.clone());
650 }
651 }
652 }
653 out
654}
655
656/// A `const` or `static` item at `i`: its name, the index past it, and whether its value holds
657/// a number or string literal.
658fn const_item(toks: &[Token], i: usize, lang: Lang) -> Option<(String, usize, bool)> {
659 if !(is_keyword(&toks[i], "const") || is_keyword(&toks[i], "static")) {
660 return None;
661 }
662 let mut j = i + 1;
663 if j < toks.len() && (is_keyword(&toks[j], "mut") || is_keyword(&toks[j], "ref")) {
664 j += 1;
665 }
666 let name_tok = toks.get(j)?;
667 if name_tok.kind != TokenKind::Ident {
668 return None; // `const fn`, `const {`, or destructuring.
669 }
670 let name = name_tok.text.clone();
671 // Find the `=` before any depth-0 `;`, `{`, `,` or `>`.
672 let mut k = j + 1;
673 let mut depth = 0isize;
674 while k < toks.len() {
675 match toks[k].kind {
676 TokenKind::Punct('<') | TokenKind::Punct('(') | TokenKind::Punct('[') => depth += 1,
677 TokenKind::Punct('>') | TokenKind::Punct(')') | TokenKind::Punct(']') => {
678 depth -= 1;
679 if depth < 0 {
680 return None;
681 }
682 }
683 TokenKind::Punct('=') if depth == 0 => break,
684 TokenKind::Punct(';') | TokenKind::Punct('{') | TokenKind::Punct(',') if depth == 0 => {
685 return None;
686 }
687 _ => {}
688 }
689 k += 1;
690 }
691 if k >= toks.len() {
692 return None;
693 }
694 // A JavaScript object or array is a table, not a scalar setting; its strings are still scanned.
695 if lang == Lang::Js && toks.get(k + 1).map_or(false, |t| is_punct(t, '{') || is_punct(t, '[')) {
696 return None;
697 }
698 let mut literal = false;
699 let mut m = k + 1;
700 let mut depth = 0isize;
701 while m < toks.len() {
702 let t = &toks[m];
703 if depth == 0 && m > k + 1 && lang == Lang::Js
704 && t.leading_trivia.iter().any(|v| matches!(v, Trivia::Newline))
705 && !matches!(toks[m - 1].kind, TokenKind::Punct(_) | TokenKind::Operator(_))
706 {
707 break; // JavaScript without a semicolon.
708 }
709 match t.kind {
710 TokenKind::Punct(';') if depth == 0 => { m += 1; break; }
711 TokenKind::Punct('(') | TokenKind::Punct('[') | TokenKind::Punct('{') => depth += 1,
712 TokenKind::Punct(')') | TokenKind::Punct(']') | TokenKind::Punct('}') => depth -= 1,
713 TokenKind::Number | TokenKind::StringLit => literal = true,
714 TokenKind::Eof => break,
715 _ => {}
716 }
717 m += 1;
718 }
719 Some((name, m, literal))
720}
721
722/// Is the string at `i` a JavaScript module specifier (`from "…"`, `import("…")`,
723/// `require("…")`), which names code rather than data?
724fn is_module_specifier(toks: &[Token], i: usize) -> bool {
725 if i >= 1 && (is_keyword(&toks[i - 1], "from") || is_ident(&toks[i - 1], "from")
726 || is_keyword(&toks[i - 1], "import"))
727 {
728 return true;
729 }
730 i >= 2 && is_punct(&toks[i - 1], '(')
731 && (is_keyword(&toks[i - 2], "import") || is_ident(&toks[i - 2], "require"))
732}
733
734/// Is this item name in the mutable vocabulary?
735fn is_mutable_name(name: &str) -> bool {
736 if name.chars().any(|c| c.is_ascii_lowercase()) {
737 return false; // Constants are upper snake case; anything else is not named data.
738 }
739 let parts: Vec<&str> = name.split('_').filter(|p| !p.is_empty()).collect();
740 if parts.contains(&"PER") {
741 return false; // A unit conversion, `SECONDS_PER_HOUR`.
742 }
743 if parts.first() == Some(&"ENABLE") {
744 return true;
745 }
746 parts.iter().any(|p| {
747 matches!(*p,
748 "MAX" | "LIMIT" | "LIMITS" | "CAP" | "CAPACITY" | "TTL" | "PORT" | "PORTS"
749 | "HOST" | "HOSTS" | "URL" | "URLS" | "MODEL" | "MODELS" | "PRICE" | "PRICES" | "FEE"
750 | "FEES" | "COST" | "COSTS" | "SCHEDULE" | "MS" | "SECS" | "SEC" | "SECONDS" | "MILLIS")
751 || p.starts_with("TIMEOUT") || p.starts_with("THRESH") || p.starts_with("RETR")
752 || p.starts_with("INTERVAL") || p.starts_with("ATTEMPT") || p.starts_with("BACKOFF")
753 })
754}
755
756/// The consts in this source that a timing call may take as its argument: bound to literal-only
757/// arithmetic, named outside the mutable vocabulary (those are flagged as named already), and not
758/// marked `// fixed:`.
759fn numeric_consts(
760 toks: &[Token],
761 lang: Lang,
762 lines: &LineIndex,
763 fixed: &BTreeSet<usize>,
764 skip: &[bool],
765)
766 -> BTreeSet<String>
767{
768 let mut out = BTreeSet::new();
769 for i in 0..toks.len() {
770 if skip[i] || fixed.contains(&lines.line_of(toks[i].span.start)) {
771 continue;
772 }
773 if let Some((name, end, _)) = const_item(toks, i, lang) {
774 if is_mutable_name(&name) {
775 continue;
776 }
777 let eq = match (i + 1..end).find(|&k| is_punct(&toks[k], '=')) {
778 Some(k) => k,
779 None => continue,
780 };
781 let mut stop = end;
782 if stop > eq + 1 && is_punct(&toks[stop - 1], ';') {
783 stop -= 1;
784 }
785 if numeric_expr(&toks[eq + 1..stop]).is_some() {
786 out.insert(name);
787 }
788 }
789 }
790 out
791}
792
793/// Is a number token nonzero?
794fn nonzero(t: &Token) -> bool {
795 t.kind == TokenKind::Number && t.text.trim_start_matches(|c| c == '0' || c == '.' || c == '_')
796 .chars().next().map_or(false, |c| c.is_ascii_digit())
797}
798
799/// Literal-only arithmetic (`30`, `5 * 60`, `(1 << 4)`), as normalised text with whether any
800/// number in it is nonzero.
801fn numeric_expr(toks: &[Token]) -> Option<(String, bool)> {
802 if toks.is_empty() {
803 return None;
804 }
805 let mut text = String::new();
806 let mut any = false;
807 let mut seen = false;
808 for t in toks {
809 let piece = match &t.kind {
810 TokenKind::Number => {
811 seen = true;
812 any = any || nonzero(t);
813 t.text.as_str()
814 }
815 TokenKind::Punct(c) if "*+-/%()".contains(*c) => t.text.as_str(),
816 TokenKind::Operator(o) if o == "<<" || o == ">>" => t.text.as_str(),
817 _ => return None,
818 };
819 if !text.is_empty() && !text.ends_with('(') && piece != ")" {
820 text.push(' ');
821 }
822 text.push_str(piece);
823 }
824 if seen { Some((text, any)) } else { None }
825}
826
827/// The normalised text of a timing call's argument list `toks[open + 1..close]`, when every
828/// argument is literal-only arithmetic or a const of `waits`, and one at least is nonzero.
829fn timing_args(toks: &[Token], waits: &BTreeSet<String>) -> Option<String> {
830 let mut args = Vec::new();
831 let mut live = false;
832 for arg in toks.split(|t| is_punct(t, ',')) {
833 if arg.len() == 1 && arg[0].kind == TokenKind::Ident && waits.contains(&arg[0].text) {
834 live = true;
835 args.push(arg[0].text.clone());
836 } else {
837 let (text, any) = numeric_expr(arg)?;
838 live = live || any;
839 args.push(text);
840 }
841 }
842 if live { Some(args.join(", ")) } else { None }
843}
844
845/// A timing call with a literal argument at `i`: its normalised text and the index past it. The
846/// argument may be literal-only arithmetic or a same-file const in `waits`.
847fn timing_call(toks: &[Token], i: usize, lang: Lang, waits: &BTreeSet<String>) -> Option<(String, usize)> {
848 let t = &toks[i];
849 if t.kind != TokenKind::Ident {
850 return None;
851 }
852 // The arguments of the flat group at `open`, which must hold no nested call.
853 let flat = |open: usize| -> Option<(usize, String)> {
854 let end = group_end(toks, open);
855 if end < open + 2 || !is_punct(&toks[end - 1], ')') {
856 return None;
857 }
858 Some((end, timing_args(&toks[open + 1..end - 1], waits)?))
859 };
860 match lang {
861 Lang::Rust => {
862 if t.text == "Duration" && i + 3 < toks.len()
863 && toks[i + 1].kind == TokenKind::Operator("::".to_string())
864 && (toks[i + 2].text.starts_with("from_") || toks[i + 2].text == "new")
865 && is_punct(&toks[i + 3], '(')
866 {
867 let (end, args) = flat(i + 3)?;
868 return Some((fmt!("Duration::{}({})", toks[i + 2].text, args), end));
869 }
870 if t.text == "sleep" && i + 1 < toks.len() && is_punct(&toks[i + 1], '(') {
871 let (end, args) = flat(i + 1)?;
872 return Some((fmt!("sleep({})", args), end));
873 }
874 None
875 }
876 Lang::Js => {
877 if (t.text == "setTimeout" || t.text == "setInterval") && i + 1 < toks.len()
878 && is_punct(&toks[i + 1], '(')
879 {
880 let end = group_end(toks, i + 1);
881 // The last argument, after the final depth-1 comma.
882 let mut depth = 0isize;
883 let mut comma = None;
884 for k in i + 1..end {
885 match toks[k].kind {
886 TokenKind::Punct('(') | TokenKind::Punct('[') | TokenKind::Punct('{') => depth += 1,
887 TokenKind::Punct(')') | TokenKind::Punct(']') | TokenKind::Punct('}') => depth -= 1,
888 TokenKind::Punct(',') if depth == 1 => comma = Some(k),
889 _ => {}
890 }
891 }
892 let c = comma?;
893 if end >= 1 && is_punct(&toks[end - 1], ')') {
894 let args = timing_args(&toks[c + 1..end - 1], waits)?;
895 return Some((fmt!("{}({})", t.text, args), end));
896 }
897 }
898 None
899 }
900 }
901}
902
903/// Rust `concat!(…)` at `i`: its literal arguments joined, and the index past it. Any other
904/// argument stands as `{}`, as in a format string.
905fn concat_macro(toks: &[Token], i: usize, lang: Lang) -> Option<(String, usize)> {
906 if lang != Lang::Rust || !is_ident(&toks[i], "concat") || i + 2 >= toks.len()
907 || !is_punct(&toks[i + 1], '!') || !is_punct(&toks[i + 2], '(')
908 {
909 return None;
910 }
911 let end = group_end(toks, i + 2);
912 let mut text = String::new();
913 let mut j = i + 3;
914 while j + 1 < end {
915 let t = &toks[j];
916 match t.kind {
917 TokenKind::StringLit => { text.push_str(string_content(&t.text)); j += 1; }
918 TokenKind::Number | TokenKind::CharLit => { text.push_str(string_content(&t.text)); j += 1; }
919 TokenKind::Punct(',') => j += 1,
920 _ => {
921 // One non-literal argument, up to its depth-0 comma.
922 text.push_str("{}");
923 while j + 1 < end && !is_punct(&toks[j], ',') {
924 j = match toks[j].kind {
925 TokenKind::Punct('(') | TokenKind::Punct('[') | TokenKind::Punct('{') => {
926 group_end(toks, j)
927 }
928 _ => j + 1,
929 };
930 }
931 }
932 }
933 }
934 Some((text, end))
935}
936
937/// The string at `i` joined with the literals that follow it in a `+` chain, and the index past
938/// the last piece. A piece may sit in a one-argument call (`String::from("…")`) or take a
939/// no-argument method (`"…".to_string()`); the chain ends at the first operand that is not a literal.
940fn plus_chain(toks: &[Token], i: usize, skip: &[bool]) -> (String, usize) {
941 let mut text = string_content(&toks[i].text).to_string();
942 let mut j = i; // The current piece's string.
943 loop {
944 let mut k = j + 1;
945 if j >= 1 && is_punct(&toks[j - 1], '(') && toks.get(k).map_or(false, |t| is_punct(t, ')')) {
946 k += 1;
947 }
948 if k + 3 < toks.len() && is_punct(&toks[k], '.') && toks[k + 1].kind == TokenKind::Ident
949 && is_punct(&toks[k + 2], '(') && is_punct(&toks[k + 3], ')')
950 {
951 k += 4;
952 }
953 match (toks.get(k), toks.get(k + 1)) {
954 (Some(p), Some(n)) if is_punct(p, '+') && n.kind == TokenKind::StringLit && !skip[k + 1] => {
955 text.push_str(string_content(&n.text));
956 j = k + 1;
957 }
958 _ => return (text, j + 1),
959 }
960 }
961}
962
963/// The content of a string literal token, without prefix, hashes or delimiters.
964fn string_content(text: &str) -> &str {
965 let s = text.trim_start_matches(|c| c == 'b' || c == 'r' || c == 'c');
966 let s = s.trim_start_matches('#').trim_end_matches('#');
967 let mut cs = s.chars();
968 match (cs.next(), s.chars().last()) {
969 (Some(a), Some(z)) if s.len() >= 2 && a == z && (a == '"' || a == '\'' || a == '`') => {
970 &s[1..s.len() - 1]
971 }
972 _ => s,
973 }
974}
975
976// fixed: top-level domains that mark a bare host name, a heuristic of the gate itself.
977const TLDS: [&str; 16] = [
978 "com", "org", "net", "io", "dev", "app", "ai", "co", "uk", "au", "gov", "edu", "cloud", "sh",
979 "me", "info",
980];
981
982// fixed: state and config file extensions, a heuristic of the gate itself.
983const STATE_EXTS: [&str; 17] = [
984 "jdat", "json", "pem", "key", "crt", "cer", "sock", "log", "db", "sqlite", "toml", "yaml",
985 "yml", "pid", "conf", "cfg", "ini",
986];
987
988// fixed: model id families of the major providers, a heuristic of the gate itself.
989const MODEL_PREFIXES: [&str; 24] = [
990 "gpt-", "claude-", "gemini-", "llama-", "llama3", "mistral-", "mixtral-", "o1-", "o3-", "o4-",
991 "text-embedding-", "whisper-", "dall-e-", "deepseek-", "qwen", "command-r", "grok-", "sonar-",
992 "pixtral-", "codestral-", "openai/", "anthropic/", "google/", "meta-llama/",
993];
994
995/// The class of a string literal's content, if it is mutable data.
996fn classify(s: &str) -> Option<Class> {
997 if s.is_empty() || s.chars().any(|c| c.is_whitespace()) || s.contains("\\n") {
998 return None;
999 }
1000 let lower = s.to_ascii_lowercase();
1001 if MODEL_PREFIXES.iter().any(|p| lower.starts_with(p)) && lower.len() > 4
1002 && !lower.ends_with('-')
1003 {
1004 return Some(Class::Model);
1005 }
1006 if let Some(p) = s.find("://") {
1007 if p > 0 && s[..p].chars().all(|c| c.is_ascii_alphanumeric() || c == '+' || c == '-' || c == '.')
1008 && s.len() > p + 3
1009 {
1010 return Some(Class::Host);
1011 }
1012 }
1013 if is_host(s) {
1014 return Some(Class::Host);
1015 }
1016 if is_path(s) {
1017 return Some(Class::Path);
1018 }
1019 None
1020}
1021
1022fn is_host(s: &str) -> bool {
1023 let (host, port) = match s.rsplit_once(':') {
1024 Some((h, p)) if !p.is_empty() && p.len() <= 5 && p.chars().all(|c| c.is_ascii_digit()) => {
1025 (h, true)
1026 }
1027 _ => (s, false),
1028 };
1029 let labels: Vec<&str> = host.split('.').collect();
1030 if labels.len() == 4 && labels.iter().all(|l| !l.is_empty() && l.len() <= 3
1031 && l.chars().all(|c| c.is_ascii_digit()))
1032 {
1033 return true; // IPv4.
1034 }
1035 if host == "localhost" {
1036 return port || s == "localhost";
1037 }
1038 labels.len() >= 2
1039 && labels.iter().all(|l| !l.is_empty()
1040 && l.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-'))
1041 && labels.last().map_or(false, |t| TLDS.contains(t))
1042}
1043
1044fn is_path(s: &str) -> bool {
1045 let path_char = |c: char| c.is_ascii_alphanumeric() || "/._-~{}".contains(c);
1046 if !s.chars().all(path_char) {
1047 return false;
1048 }
1049 let mut cs = s.chars();
1050 let first = cs.next();
1051 let second = cs.next();
1052 match (first, second) {
1053 // Two characters at least after the slash: `/t` is a command switch, not a location.
1054 (Some('/'), Some(c)) if s.len() >= 3 && (c.is_ascii_alphanumeric() || c == '.' || c == '_') => {
1055 return true;
1056 }
1057 _ => {}
1058 }
1059 if (s.starts_with("~/") || s.starts_with("./") || s.starts_with("../")) && s.len() > 2 {
1060 return true;
1061 }
1062 match s.rsplit_once('.') {
1063 Some((stem, ext)) => {
1064 !stem.is_empty() && !stem.ends_with('/') && STATE_EXTS.contains(&ext)
1065 && stem.chars().next().map_or(false, |c| c.is_ascii_alphanumeric() || c == '{')
1066 }
1067 None => false,
1068 }
1069}