Skip to main content

kevy_cli/
doctor.rs

1//! `doctor` — run every table's `VERIFY` and turn the counters into an
2//! exit code.
3//!
4//! Lesson 8 of the migration playbook: *make `VERIFY` part of
5//! operations, not part of the migration.* The counters are fresh on
6//! every call and cheap enough for a cron; what was missing is the
7//! shell that turns them into something a cron can act on.
8//!
9//! The mapping is the lesson's own words, not a new opinion:
10//!
11//! * `drift` and `missing` **should be zero forever** — non-zero is a
12//!   failure;
13//! * non-zero `duplicates` on an ORDERPATH means **pagination needs a
14//!   bounded tie-break** — a warning about a design choice, not a
15//!   corruption;
16//! * `absent` / `excluded` / `coerce_failures` **name the rows each
17//!   exclusion cause claimed** — reported, never failed on, because
18//!   every one of them is a legitimate state.
19//!
20//! And one thing the lesson could not have known: `TABLE.VERIFY`
21//! answers `-INDEXBUILDING` while a backfill is still running. A cron
22//! that read that as a failure would page someone every time an index
23//! was declared, so it is its own outcome.
24//!
25//! ```
26//! use kevy_cli::doctor::{Health, check_table, table_names};
27//! # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
28//! let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
29//! client.request_borrowed(&[
30//!     b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
31//!     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range",
32//! ])?;
33//! client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
34//! client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
35//! for name in table_names(&mut client)? {
36//!     let h = check_table(&mut client, &name)?;
37//!     assert_eq!(h.health, Health::Ok, "{name}: {}", h.reported);
38//! }
39//! # Ok::<(), Box<dyn std::error::Error>>(())
40//! ```
41
42use std::io;
43use std::process::ExitCode;
44
45use crate::link::Link;
46use kevy_resp_client::Reply;
47
48mod verify;
49use verify::{classify, listed_names, report};
50pub(crate) use verify::{fields, run_on};
51
52/// What `doctor` concluded about one table.
53///
54/// ```
55/// use kevy_cli::doctor::{Health, check_table};
56/// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
57/// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
58/// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
59/// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
60/// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
61/// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
62/// // what a cron wrapper does with each verdict
63/// let pages_someone = |h: &Health| matches!(h, Health::Drift { .. });
64/// assert!(!pages_someone(&check_table(&mut client, "users")?.health));
65/// assert!(pages_someone(&check_table(&mut client, "no-such-table")?.health));
66/// # Ok::<(), Box<dyn std::error::Error>>(())
67/// ```
68#[derive(Debug, Clone, PartialEq, Eq, Hash)]
69#[non_exhaustive]
70pub enum Health {
71    /// Every counter where it should be.
72    ///
73    /// ```
74    /// use kevy_cli::doctor::{Health, check_table};
75    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
76    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
77    /// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
78    /// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
79    /// client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
80    /// client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
81    /// assert_eq!(check_table(&mut client, "users")?.health, Health::Ok);
82    /// # Ok::<(), Box<dyn std::error::Error>>(())
83    /// ```
84    Ok,
85    /// `drift` or `missing` is non-zero — the index and the keyspace
86    /// disagree, which is the thing VERIFY exists to make falsifiable.
87    ///
88    /// ```
89    /// use kevy_cli::doctor::{Health, check_table};
90    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
91    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
92    /// // a VERIFY that cannot be answered is drift, never a pass
93    /// let h = check_table(&mut client, "orders")?;
94    /// assert!(matches!(h.health, Health::Drift { .. }));
95    /// # Ok::<(), Box<dyn std::error::Error>>(())
96    /// ```
97    Drift {
98        /// Which counters were non-zero, with their values.
99        ///
100        /// ```
101        /// use kevy_cli::doctor::{Health, check_table};
102        /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
103        /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
104        /// let Health::Drift { detail } = check_table(&mut client, "orders")?.health else {
105        ///     panic!("an undeclared table cannot verify clean");
106        /// };
107        /// assert!(detail.contains("no such table"), "{detail}");
108        /// # Ok::<(), Box<dyn std::error::Error>>(())
109        /// ```
110        detail: String,
111    },
112    /// Non-zero `duplicates`: not corruption, but pagination over this
113    /// path needs a bounded tie-break or pages will repeat rows.
114    ///
115    /// ```
116    /// use kevy_cli::doctor::{Health, check_table};
117    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
118    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
119    /// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
120    /// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
121    /// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
122    /// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
123    /// client.request_borrowed(&[b"HSET", b"user:3", b"id", b"3", b"age", b"30"])?; // a second 30
124    /// let h = check_table(&mut client, "users")?;
125    /// assert!(matches!(h.health, Health::NeedsTieBreak { .. }), "{:?}", h.health);
126    /// # Ok::<(), Box<dyn std::error::Error>>(())
127    /// ```
128    NeedsTieBreak {
129        /// How many duplicate order values were found.
130        ///
131        /// ```
132        /// use kevy_cli::doctor::{Health, check_table};
133        /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
134        /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
135        /// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
136        /// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
137        /// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
138        /// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
139        /// client.request_borrowed(&[b"HSET", b"user:3", b"id", b"3", b"age", b"30"])?; // a second 30
140        /// let h = check_table(&mut client, "users")?;
141        /// assert_eq!(h.health, Health::NeedsTieBreak { duplicates: 1 });
142        /// # Ok::<(), Box<dyn std::error::Error>>(())
143        /// ```
144        duplicates: u64,
145    },
146    /// A backfill is still running. Not a verdict either way.
147    ///
148    /// ```
149    /// use kevy_cli::doctor::Health;
150    /// // an index still backfilling says nothing about drift: wait and ask again
151    /// let retry_later = |h: &Health| matches!(h, Health::Building);
152    /// assert!(retry_later(&Health::Building));
153    /// assert!(!retry_later(&Health::Ok));
154    /// ```
155    Building,
156}
157
158/// One table's name and what was concluded about it.
159///
160/// ```
161/// use kevy_cli::doctor::{Health, check_table};
162/// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
163/// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
164/// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
165/// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
166/// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
167/// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
168/// let h = check_table(&mut client, "users")?;
169/// println!("{}  {:?}  ({})", h.name, h.health, h.reported);
170/// assert_eq!((h.name.as_str(), h.health), ("users", Health::Ok));
171/// # Ok::<(), Box<dyn std::error::Error>>(())
172/// ```
173#[derive(Debug, Clone, PartialEq, Eq, Hash)]
174#[non_exhaustive]
175pub struct TableHealth {
176    /// The declared table name.
177    ///
178    /// ```
179    /// use kevy_cli::doctor::check_table;
180    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
181    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
182    /// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
183    /// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
184    /// assert_eq!(check_table(&mut client, "users")?.name, "users");
185    /// # Ok::<(), Box<dyn std::error::Error>>(())
186    /// ```
187    pub name: String,
188    /// The verdict.
189    ///
190    /// ```
191    /// use kevy_cli::doctor::{Health, check_table};
192    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
193    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
194    /// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
195    /// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
196    /// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
197    /// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
198    /// assert_eq!(check_table(&mut client, "users")?.health, Health::Ok);
199    /// # Ok::<(), Box<dyn std::error::Error>>(())
200    /// ```
201    pub health: Health,
202    /// The counters worth showing whatever the verdict — the exclusion
203    /// causes, which are legitimate states rather than problems.
204    ///
205    /// ```
206    /// use kevy_cli::doctor::check_table;
207    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
208    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
209    /// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
210    /// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
211    /// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
212    /// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
213    /// let h = check_table(&mut client, "users")?;
214    /// assert!(h.reported.starts_with("rows 2 · entries 2"), "{}", h.reported);
215    /// # Ok::<(), Box<dyn std::error::Error>>(())
216    /// ```
217    pub reported: String,
218}
219
220/// Every declared table's name, in declaration order.
221///
222/// ```
223/// use kevy_cli::doctor::table_names;
224/// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
225/// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
226/// assert!(table_names(&mut client)?.is_empty());
227/// client.request_borrowed(&[
228///     b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
229///     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range",
230/// ])?;
231/// assert_eq!(table_names(&mut client)?, ["users"]);
232/// # Ok::<(), Box<dyn std::error::Error>>(())
233/// ```
234pub fn table_names(client: &mut dyn Link) -> io::Result<Vec<String>> {
235    let Reply::Array(tables) = client.request_borrowed(&[b"TABLE.LIST"])? else {
236        return Ok(Vec::new());
237    };
238    Ok(tables
239        .iter()
240        .filter_map(|t| {
241            let Reply::Array(items) = t else { return None };
242            fields(items).into_iter().find(|(k, _)| k == "name").map(|(_, v)| v)
243        })
244        .collect())
245}
246
247/// Verify one table and read its counters against lesson 8's mapping.
248///
249/// ```
250/// use kevy_cli::doctor::{Health, check_table};
251/// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
252/// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
253/// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
254/// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
255/// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
256/// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
257/// let h = check_table(&mut client, "users")?;
258/// assert_eq!(h.health, Health::Ok);
259/// # Ok::<(), Box<dyn std::error::Error>>(())
260/// ```
261pub fn check_table(client: &mut dyn Link, name: &str) -> io::Result<TableHealth> {
262    check_with(client, b"TABLE.VERIFY", name)
263}
264
265/// The same reading for `IDX.VERIFY` or `VIEW.VERIFY`, whose replies are
266/// one group of counters rather than one per index.
267fn check_with(client: &mut dyn Link, verb: &[u8], name: &str) -> io::Result<TableHealth> {
268    let reply = client.request_borrowed(&[verb, name.as_bytes()])?;
269    let reply = match reply {
270        Reply::Array(items) if matches!(items.first(), Some(Reply::Bulk(_))) => {
271            Reply::Array(vec![Reply::Array(items)])
272        }
273        other => other,
274    };
275    if let Reply::Error(e) = &reply {
276        let msg = String::from_utf8_lossy(e);
277        let health = if msg.starts_with("INDEXBUILDING") {
278            Health::Building
279        } else {
280            Health::Drift { detail: msg.into_owned() }
281        };
282        return Ok(TableHealth { name: name.to_string(), health, reported: String::new() });
283    }
284    // The reply is per-index groups plus a spot-check group; summing the
285    // counters across groups is the table-level answer.
286    let Reply::Array(groups) = reply else {
287        return Ok(TableHealth {
288            name: name.to_string(),
289            health: Health::Drift { detail: "unreadable VERIFY reply".into() },
290            reported: String::new(),
291        });
292    };
293    let mut sums: std::collections::BTreeMap<String, u64> = Default::default();
294    for g in &groups {
295        if let Reply::Array(items) = g {
296            for (k, v) in fields(items) {
297                if let Ok(n) = v.parse::<u64>() {
298                    *sums.entry(k).or_insert(0) += n;
299                }
300            }
301        }
302    }
303    let get = |k: &str| sums.get(k).copied().unwrap_or(0);
304    let reported = format!(
305        "rows {} · entries {} · absent {} · excluded {} · coerce_failures {}",
306        get("rows"),
307        get("entries"),
308        get("absent"),
309        get("excluded"),
310        get("coerce_failures")
311    );
312    Ok(TableHealth { name: name.to_string(), health: classify(&groups), reported })
313}
314
315/// Check every table and print one line each. Exit non-zero only on
316/// drift, unless `on_warning` says a warning fails too — by default a
317/// warning is information, and a cron that fails on information stops
318/// being read.
319///
320/// ```
321/// use kevy_cli::doctor::{OnWarning, run};
322/// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
323/// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
324/// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
325/// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
326/// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
327/// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
328/// let code = run(&mut client, OnWarning::Report)?; // prints one line per table
329/// assert_eq!(code, std::process::ExitCode::SUCCESS);
330/// # Ok::<(), Box<dyn std::error::Error>>(())
331/// ```
332pub fn run(client: &mut dyn Link, on_warning: OnWarning) -> io::Result<ExitCode> {
333    run_scoped(client, on_warning, Scope::default())
334}
335
336/// What a warning (duplicates on an ORDERPATH) does to `doctor`'s exit
337/// code. Drift fails either way.
338///
339/// ```
340/// use kevy_cli::doctor::OnWarning;
341/// // `doctor --warn-is-failure`
342/// assert_ne!(OnWarning::Fail, OnWarning::default());
343/// ```
344#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
345#[non_exhaustive]
346pub enum OnWarning {
347    /// Print the warning and still exit successfully.
348    #[default]
349    ///
350    /// ```
351    /// use kevy_cli::doctor::{OnWarning, run};
352    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
353    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
354    /// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
355    /// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
356    /// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
357    /// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
358    /// client.request_borrowed(&[b"HSET", b"user:3", b"id", b"3", b"age", b"30"])?; // a second 30
359    /// // the duplicate warns, and the cron still succeeds
360    /// assert_eq!(run(&mut client, OnWarning::Report)?, std::process::ExitCode::SUCCESS);
361    /// # Ok::<(), Box<dyn std::error::Error>>(())
362    /// ```
363    Report,
364    /// Exit non-zero when anything warned (`--warn-is-failure`).
365    ///
366    /// ```
367    /// use kevy_cli::doctor::{OnWarning, run};
368    /// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
369    /// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
370    /// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
371    /// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
372    /// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
373    /// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
374    /// client.request_borrowed(&[b"HSET", b"user:3", b"id", b"3", b"age", b"30"])?; // a second 30
375    /// assert_eq!(run(&mut client, OnWarning::Fail)?, std::process::ExitCode::FAILURE);
376    /// # Ok::<(), Box<dyn std::error::Error>>(())
377    /// ```
378    Fail,
379}
380
381/// What `doctor` verifies besides tables. The default is tables only.
382///
383/// ```
384/// use kevy_cli::doctor::Scope;
385/// // `doctor --indexes --views`
386/// let everything = Scope::default().with_indexes(true).with_views(true);
387/// assert!(everything.indexes && everything.views);
388/// assert!(!Scope::default().indexes);
389/// ```
390#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
391#[non_exhaustive]
392pub struct Scope {
393    /// Indexes declared on their own (not compiled from a table).
394    ///
395    /// ```
396    /// // `doctor --indexes`: an index `users.age` belongs to table `users`
397    /// // and is verified with it; only an index no table compiled is added.
398    /// let s = kevy_cli::doctor::Scope::default().with_indexes(true);
399    /// assert!(s.indexes);
400    /// ```
401    pub indexes: bool,
402    /// Views.
403    ///
404    /// ```
405    /// // `doctor --views`: VIEW.VERIFY for every view VIEW.LIST names.
406    /// let s = kevy_cli::doctor::Scope::default().with_views(true);
407    /// assert!(s.views);
408    /// ```
409    pub views: bool,
410}
411
412impl Scope {
413    /// Also verify indexes no table compiled (`--indexes`).
414    ///
415    /// ```
416    /// let s = kevy_cli::doctor::Scope::default().with_indexes(true);
417    /// assert!(s.indexes && !s.views);
418    /// ```
419    pub fn with_indexes(mut self, indexes: bool) -> Self {
420        self.indexes = indexes;
421        self
422    }
423
424    /// Also verify every view (`--views`).
425    ///
426    /// ```
427    /// let s = kevy_cli::doctor::Scope::default().with_views(true);
428    /// assert!(s.views && !s.indexes);
429    /// ```
430    pub fn with_views(mut self, views: bool) -> Self {
431        self.views = views;
432        self
433    }
434}
435
436/// [`run`], also verifying bare indexes and views when `scope` says so.
437///
438/// ```
439/// use kevy_cli::doctor::{OnWarning, Scope, run_scoped};
440/// # let port = include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/doc_server/serve.rs"));
441/// let mut client = kevy_resp_client::RespClient::connect("127.0.0.1", port)?;
442/// # client.request_borrowed(&[b"TABLE.DECLARE", b"users", b"PREFIX", b"user:", b"PK", b"id",
443/// #     b"COLUMN", b"id", b"i64", b"COLUMN", b"age", b"i64", b"INDEX", b"age", b"range"])?;
444/// # client.request_borrowed(&[b"HSET", b"user:1", b"id", b"1", b"age", b"30"])?;
445/// # client.request_borrowed(&[b"HSET", b"user:2", b"id", b"2", b"age", b"41"])?;
446/// let scope = Scope::default().with_indexes(true).with_views(true);
447/// let code = run_scoped(&mut client, OnWarning::Report, scope)?;
448/// assert_eq!(code, std::process::ExitCode::SUCCESS);
449/// # Ok::<(), Box<dyn std::error::Error>>(())
450/// ```
451pub fn run_scoped(
452    client: &mut dyn Link,
453    on_warning: OnWarning,
454    scope: Scope,
455) -> io::Result<ExitCode> {
456    let tables = table_names(client)?;
457    let mut targets: Vec<(&[u8], &str, String)> =
458        tables.iter().map(|n| (&b"TABLE.VERIFY"[..], "", n.clone())).collect();
459    if scope.indexes {
460        let bare = listed_names(client, b"IDX.LIST")?
461            .into_iter()
462            .filter(|n| !tables.iter().any(|t| n.starts_with(&format!("{t}."))));
463        targets.extend(bare.map(|n| (&b"IDX.VERIFY"[..], "index ", n)));
464    }
465    if scope.views {
466        targets.extend(
467            listed_names(client, b"VIEW.LIST")?
468                .into_iter()
469                .map(|n| (&b"VIEW.VERIFY"[..], "view ", n)),
470        );
471    }
472    if targets.is_empty() {
473        // Tables only: the words the migration playbook quotes.
474        let what =
475            if scope.indexes || scope.views { "nothing declared" } else { "no tables declared" };
476        println!("doctor: {what} — nothing to verify");
477        return Ok(ExitCode::SUCCESS);
478    }
479    let noun = if scope.indexes || scope.views { "checked" } else { "table(s)" };
480    report(client, &targets, on_warning, noun)
481}