mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
//! What the product publishes about itself, read and checked.
//!
//! # Why this file exists
//!
//! Every other proof in this suite asks what the product does. None of them
//! ever opened the manifest or the readme, so everything written there was
//! true only while somebody remembered it. That is the shape of the root cause
//! this file answers: a rule declared with no command that executes it does not
//! hold, it merely reads as though it does.
//!
//! It was not a theoretical gap. The readme told a reader to install with a
//! feature that does not exist in the manifest, and in the same breath
//! contradicted the manifest's own central claim about the build. Both files
//! were internally consistent; the pair was wrong, and nothing read the pair.
//!
//! # What is deliberately not required here
//!
//! The three keys that link a package to a public address, and the badge that
//! links a readme to a documentation page. There is no public address, and a
//! made-up one promises a destination that does not exist. The omission is a
//! decision, so this file demands that the decision stay written down: either
//! the keys are present, or `G-006` is alive in the gaps file. What it refuses
//! is the third state, where the keys are absent and nothing says why.

use std::collections::BTreeSet;

// Each file here uses the part of the shared module that it needs, so a helper
// unused by this one is not dead code.
#[allow(dead_code)]
mod support;

use support::Sandbox;

/// The documents that promise to describe every command the product serves.
///
/// The guide is where a person looks a command up, and the two skills are what
/// an agent is handed instead of the guide. All three make the same promise, so
/// all three are held to it.
///
/// The reference is held to it for a different reason. It is generated from the
/// binary by `cargo xtask gen-docs`, so it cannot fall behind by
/// being forgotten — only by nobody rerunning the generator. This assertion is
/// what turns that omission into a red test instead of a stale page.
const DOCUMENTS_THAT_COVER_EVERY_COMMAND: [(&str, &str); 6] = [
    ("docs/HOW_TO_USE.md", include_str!("../docs/HOW_TO_USE.md")),
    (
        "docs/HOW_TO_USE.pt-BR.md",
        include_str!("../docs/HOW_TO_USE.pt-BR.md"),
    ),
    ("docs/COMMANDS.md", include_str!("../docs/COMMANDS.md")),
    (
        "docs/COMMANDS.pt-BR.md",
        include_str!("../docs/COMMANDS.pt-BR.md"),
    ),
    (
        "skills/mariadb-cli-en/SKILL.md",
        include_str!("../skills/mariadb-cli-en/SKILL.md"),
    ),
    (
        "skills/mariadb-cli-pt/SKILL.md",
        include_str!("../skills/mariadb-cli-pt/SKILL.md"),
    ),
];

/// The manifest, read as text rather than parsed.
///
/// Read as text on purpose: a parser would answer what cargo understands, and
/// the question here is what a person opening the file would find.
const MANIFEST: &str = include_str!("../Cargo.toml");

/// The readme, which is also the front page of the published package.
const README: &str = include_str!("../README.md");

/// The gaps file, which is where a deliberate omission is required to live.
///
/// Read from disk rather than embedded. It was `include_str!` until the record
/// moved to the root and out of the published allowlist: a macro that resolves
/// while compiling would have made the file a build dependency of the archive,
/// and an archive that carries the proof without the document it reads cannot
/// compile its own tests for whoever downloaded it. Absent, the proof below
/// says so and declines to pass rather than passing over nothing.
fn gaps() -> Option<String> {
    std::fs::read_to_string(std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("gaps.md")).ok()
}

/// The readme in the other language the product answers in.
const README_PT: &str = include_str!("../README.pt-BR.md");

/// The short map a reading agent opens first.
const SHORT_MAP: &str = include_str!("../llms.txt");

/// The same map with the reasoning kept.
const FULL_MAP: &str = include_str!("../llms-full.txt");

/// The short map in the other language the product answers in.
const SHORT_MAP_PT: &str = include_str!("../llms.pt-BR.txt");

/// The full map in the other language the product answers in.
const FULL_MAP_PT: &str = include_str!("../llms-full.pt-BR.txt");

/// Every map the archive publishes, named once for every proof that reads maps.
///
/// Written here rather than inside each proof because three proofs below used to
/// carry three hand-written lists, and the three had drifted apart: one named two
/// maps, one named three, and the fourth map was named by none of them. Nothing
/// failed, because that map happens to lead only to paths a glob already reaches.
/// The day one of its links moved, the proof that catches a destination the
/// archive does not carry would have had nothing to catch it with — which is the
/// very defect the proof below was written after, repeated one language over.
const MAPS: [(&str, &str); 4] = [
    ("llms.txt", SHORT_MAP),
    ("llms-full.txt", FULL_MAP),
    ("llms.pt-BR.txt", SHORT_MAP_PT),
    ("llms-full.pt-BR.txt", FULL_MAP_PT),
];

/// The documentation page must be built for a named target.
///
/// The registry's default set changed once already, and a page can stop being
/// built without anybody editing this file. Naming the target is what makes
/// that a decision rather than an inheritance.
#[test]
fn the_documentation_page_is_built_for_a_named_target() {
    let section = section_of(MANIFEST, "[package.metadata.docs.rs]")
        .expect("the manifest declares how its documentation is built");

    assert!(
        section.contains("targets = ["),
        "the documentation section names no target, so the page is built for \
         whatever the registry defaults to that week: {section}"
    );
    assert!(
        section.contains("features = ["),
        "the page must describe the same build the install produces"
    );
}

/// Every feature the readme tells somebody to use has to exist.
///
/// This is the defect that was measured. The readme offered a second crypto
/// provider behind a feature the manifest does not declare, so following the
/// readme produced an unknown-feature error, and the same paragraph denied the
/// manifest's claim that every published build installs without a C compiler.
#[test]
fn every_feature_the_readme_names_exists_in_the_manifest() {
    let declared = declared_features();
    let offered = features_named_in(README);

    let invented: Vec<&String> = offered.difference(&declared).collect();
    assert!(
        invented.is_empty(),
        "the readme tells a reader to install with {invented:?}, which the \
         manifest does not declare; the manifest offers {declared:?}"
    );
}

/// The readme carries the two sections a published crate is read for.
///
/// The minimum toolchain and the licence are the two questions asked before
/// anything is installed, and the names are fixed rather than free, because a
/// reader scanning for them scans for those words.
#[test]
fn the_readme_answers_the_two_questions_asked_before_installing() {
    let headings = headings_of(README);

    assert!(
        headings.iter().any(|heading| heading == "## MSRV"),
        "no minimum toolchain section; the readme has {headings:?}"
    );
    assert!(
        headings.iter().any(|heading| heading == "## License"),
        "no licence section under that name; the readme has {headings:?}"
    );
}

/// The minimum toolchain the readme states is the one the manifest enforces.
///
/// Two places that must agree, which is the shape of every defect this audit
/// found. The manifest is what cargo refuses against; the readme is what a
/// person reads, and a reader who trusts a stale number installs a toolchain
/// that cannot build the product.
#[test]
fn the_stated_minimum_toolchain_is_the_one_the_manifest_enforces() {
    let enforced = value_of(MANIFEST, "rust-version")
        .expect("the manifest declares a minimum toolchain, so cargo can refuse by name");

    assert!(
        README.contains(&enforced),
        "the readme does not carry the minimum toolchain `{enforced}` that the \
         manifest enforces, so the two can drift without anything noticing"
    );
}

/// A reading agent finds a map, and the map points at files that exist.
#[test]
fn the_maps_for_a_reading_agent_exist_and_point_somewhere_real() {
    for (name, map) in MAPS {
        assert!(
            map.starts_with("# mariadb-cli"),
            "{name} does not open by naming the product"
        );
        // Until 2026-08-26 this required the OPPOSITE: that every map name
        // `docs_prd/prd_mariadb-cli.md`. The owner then decided the
        // requirements directory is working material in its entirety, and a
        // map that names a file the archive does not carry sends whoever
        // downloads the crate to nothing. So the requirement inverted, and
        // what the map owes a reader is the published surface instead.
        assert!(
            !map.contains("docs_prd/"),
            "{name} names the requirements directory, which is working material \
             and travels neither in the archive nor in the repository, so the \
             reader is sent to a file that is not there"
        );
        assert!(
            map.contains("docs/COMMANDS"),
            "{name} does not point at the command reference, which is the \
             published document that answers what the product does"
        );
    }

    // Named in the readme, so somebody who opens only that file still learns
    // the maps are there. Each readme is asked about its own pair, because a
    // reader who opens the translated readme is led to the translated maps and
    // would otherwise be led to a language they did not ask for.
    for (readme, short, full) in [
        ("README.md", "llms.txt", "llms-full.txt"),
        ("README.pt-BR.md", "llms.pt-BR.txt", "llms-full.pt-BR.txt"),
    ] {
        let text = if readme == "README.md" {
            README
        } else {
            README_PT
        };
        assert!(
            text.contains(short) && text.contains(full),
            "{readme} does not mention its maps, so nothing leads to them"
        );
    }
}

/// Every command the product serves is named by the documents that promise all.
///
/// # Why the surface is read from the binary and not from a list
///
/// A list written here would be a second copy of the command tree, and the two
/// would agree only while somebody kept them equal. The tree the binary answers
/// with IS the surface, so a leaf served tomorrow arrives here without anybody
/// editing this file — which is the only way a coverage claim survives growth.
///
/// # What this refuses
///
/// A command that is served and appears in no guide. That state is invisible
/// otherwise: the suite stays green, the binary answers correctly, and the only
/// person who finds out is the reader who looked the command up and did not
/// find it. The coverage was checked once by hand while the guides were being
/// written, and a check performed once is a check that expires.
#[test]
fn every_served_command_is_named_by_the_documents_that_promise_all_of_them() {
    let sandbox = Sandbox::new();

    let served: Vec<String> = sandbox
        .run(&["meta", "commands"])
        .rows()
        .iter()
        .filter_map(|row| {
            let name = row["name"].as_str()?;
            (row["state"].as_str() == Some("served")).then(|| name.to_owned())
        })
        .collect();

    // Without this the whole proof passes on an empty set, the same way the
    // link reader beside it would have.
    assert!(
        served.len() >= 60,
        "the binary answered with {} served commands, which is too few for this \
         proof to be measuring the surface at all",
        served.len()
    );

    for (name, text) in DOCUMENTS_THAT_COVER_EVERY_COMMAND {
        let absent: Vec<&String> = served
            .iter()
            .filter(|command| !text.contains(command.as_str()))
            .collect();

        assert!(
            absent.is_empty(),
            "{name} promises to describe every command and names none of these, \
             so a reader looking one up finds nothing: {absent:?}"
        );
    }
}

/// Every served command carries a runnable invocation in both skills.
///
/// # Why naming the command is not enough
///
/// The proof above holds the skills to naming all sixty-three, and a document
/// can satisfy that while teaching nobody how to call a single one: a line that
/// says what `server kill` is for contains the words `server kill`. That is
/// exactly what these two files did until somebody counted — sixty-three names,
/// and a ready invocation for fifteen of them. The forty-eight that a reader
/// could not have guessed the argv for were the ones a skill exists to supply.
///
/// So this reads for the command with something after it, which is the shape of
/// a call rather than the shape of a mention.
#[test]
fn every_served_command_is_shown_being_run_by_both_skills() {
    let sandbox = Sandbox::new();

    let served: Vec<String> = sandbox
        .run(&["meta", "commands"])
        .rows()
        .iter()
        .filter_map(|row| {
            let name = row["name"].as_str()?;
            (row["state"].as_str() == Some("served")).then(|| name.to_owned())
        })
        .collect();

    // Same guard the proof above carries: without it an empty answer from the
    // binary would make this pass while measuring nothing at all.
    assert!(
        served.len() >= 60,
        "the binary answered with {} served commands, which is too few for this \
         proof to be measuring the surface at all",
        served.len()
    );

    for (name, text) in [
        (
            "skills/mariadb-cli-en/SKILL.md",
            include_str!("../skills/mariadb-cli-en/SKILL.md"),
        ),
        (
            "skills/mariadb-cli-pt/SKILL.md",
            include_str!("../skills/mariadb-cli-pt/SKILL.md"),
        ),
    ] {
        let unshown: Vec<&String> = served
            .iter()
            .filter(|command| {
                // Two endings rather than one. A leaf with a required flag is
                // shown with something after it, and a leaf that needs nothing
                // is a complete call on its own — `mariadb-cli conn list` ends
                // at the closing backtick. Reading only for the space would
                // have demanded an argument the command does not take.
                !text.contains(&format!("`mariadb-cli {command} "))
                    && !text.contains(&format!("`mariadb-cli {command}`"))
            })
            .collect();

        assert!(
            unshown.is_empty(),
            "{name} names these commands without ever showing one being run, \
             which teaches the reader the word and not the call: {unshown:#?}"
        );
    }
}

/// Every schema file on disk is named by the index that claims to list them.
///
/// The index is generated by `cargo xtask gen-schemas`, so it cannot fall
/// behind by being written badly — only by nobody rerunning the generator. This
/// is what turns that omission into a red test instead of a directory of
/// sixty-five files whose readme names three of them and tells the reader to go
/// list the rest himself. That is what it did until somebody counted: three
/// named, sixty-two unnamed, under a suite that was entirely green.
#[test]
fn every_published_schema_is_named_by_the_index_that_lists_them() {
    let index_en = include_str!("../docs/schemas/README.md");
    let index_pt = include_str!("../docs/schemas/README.pt-BR.md");

    let files: Vec<String> = std::fs::read_dir("docs/schemas")
        .expect("the schema directory is part of the published package")
        .filter_map(|entry| {
            let name = entry.ok()?.file_name().to_string_lossy().into_owned();
            name.ends_with(".schema.json").then_some(name)
        })
        .collect();

    // Without this the proof passes on an empty directory, which is the same
    // failure it exists to catch, wearing the opposite disguise.
    assert!(
        files.len() >= 60,
        "found {} schema files, which is too few for this proof to be measuring anything",
        files.len()
    );

    for (name, index) in [("README.md", index_en), ("README.pt-BR.md", index_pt)] {
        let absent: Vec<&String> = files.iter().filter(|file| !index.contains(*file)).collect();

        assert!(
            absent.is_empty(),
            "docs/schemas/{name} claims to list every schema and names none of these, \
             so run `cargo xtask gen-schemas`: {absent:#?}"
        );
    }
}

/// Every destination a map names is carried by the archive that carries the map.
///
/// The proof above reads one link and calls the map checked. That was enough to
/// let a second link point at a file the allowlist never published: the map
/// travelled, the destination did not, and nothing failed. This reads every
/// link instead of one, which is the difference between a sample and a guard.
///
/// A path under `src` is covered by the glob the manifest already states, so it
/// is checked for existence alone. Anything else has to be named, because a
/// glob that reaches it would be a glob that reaches its neighbours too.
#[test]
fn every_destination_the_maps_name_is_published_and_not_merely_linked() {
    let allowlist = section_of(MANIFEST, "include = [").expect("the manifest ships an allowlist");
    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));

    for (name, map) in MAPS {
        let targets = link_targets(map);

        // Without this the whole proof passes on an empty set, which is what a
        // reader-of-links proof looks like the day the link syntax changes and
        // the reader stops finding anything.
        assert!(
            targets.len() >= 3,
            "{name} yielded {} link targets, so this proof is checking almost \
             nothing; either the map lost its links or the reader stopped \
             finding them",
            targets.len()
        );

        for target in targets {
            assert!(
                root.join(&target).exists(),
                "{name} leads to `{target}`, which is not in the repository"
            );

            assert!(
                published_by(allowlist, &target),
                "{name} leads to `{target}` and the allowlist does not publish \
                 it, so whoever downloads the crate opens a link to nothing"
            );
        }
    }
}

/// True when the allowlist reaches one repository-relative path.
///
/// A path is reached either by its own name or by a tree pattern above it. The
/// tree case is matched on the directory and the extension alone, which is what
/// `dir/**/*.ext` means and all this needs to decide.
fn published_by(allowlist: &str, target: &str) -> bool {
    if allowlist.contains(target) {
        return true;
    }

    let Some((directory, rest)) = target.split_once('/') else {
        return false;
    };
    let Some(extension) = rest.rsplit_once('.').map(|(_, tail)| tail) else {
        return false;
    };

    allowlist.contains(&format!("{directory}/**/*.{extension}"))
}

/// The repository-relative target of every markdown link in a document.
///
/// External addresses are skipped: this asks what the archive has to carry,
/// and an address is not carried by anything.
fn link_targets(text: &str) -> Vec<String> {
    let mut found = Vec::new();
    for (offset, _) in text.match_indices("](") {
        let rest = &text[offset + 2..];
        let Some(end) = rest.find(')') else { continue };
        let target = &rest[..end];
        if target.starts_with("http") || target.starts_with('#') {
            continue;
        }
        found.push(target.to_owned());
    }
    found
}

/// Whatever travels in the published archive has to include what is claimed.
///
/// The allowlist is what decides the archive. The readmes name the files a
/// reader is told to open, and shipping a package whose readme points at files
/// it does not carry is publishing an answer without its question.
///
/// Both readmes are answered for, and so are both pairs of maps. The list held
/// only the English half while the translated half was published beside it and
/// guarded by nothing, which is an omission that costs nothing until the day the
/// allowlist is edited by somebody reading this proof to learn what matters.
#[test]
fn the_published_archive_carries_what_the_readme_points_at() {
    let allowlist = section_of(MANIFEST, "include = [").expect("the manifest ships an allowlist");

    for named in [
        "/README.md",
        "/README.pt-BR.md",
        "/llms.txt",
        "/llms-full.txt",
        "/llms.pt-BR.txt",
        "/llms-full.pt-BR.txt",
        // `/docs_prd/prd_mariadb-cli.md` stood here until 2026-08-26. The owner
        // decided the requirements directory is working material in its
        // entirety, so the maps and readmes no longer lead a reader to it and
        // the allowlist no longer carries it. Requiring it here would be this
        // proof holding a decision that was reversed.
    ] {
        assert!(
            allowlist.contains(named),
            "the readme leads a reader to `{named}` and the archive does not \
             carry it"
        );
    }
}

/// A link to the code and the manual is either published or explained.
///
/// The third state is what this refuses: the keys absent and nothing saying
/// why. An omission that stays a decision is fine; an omission that quietly
/// becomes an oversight is what this catches on the day it happens.
#[test]
fn the_missing_links_to_the_code_are_a_decision_and_not_an_oversight() {
    let links = ["repository", "homepage", "documentation"];
    let published: Vec<&str> = links
        .into_iter()
        .filter(|key| value_of(MANIFEST, key).is_some())
        .collect();

    let Some(gaps) = gaps() else {
        eprintln!(
            "SKIPPED: the_missing_links_to_the_code_are_a_decision_and_not_an_oversight \
             needs gaps.md, which is local working material and does not travel in \
             the archive. This proof did NOT pass; it did not run."
        );
        return;
    };

    if published.len() == links.len() {
        assert!(
            !gaps.contains("## G-006"),
            "the manifest publishes all three links and the gaps file still \
             carries G-006, which describes their absence"
        );
        return;
    }

    assert!(
        gaps.contains("## G-006"),
        "the manifest publishes only {published:?} of {links:?} and no gap \
         explains the rest, so the omission reads as forgetting"
    );
}

/// The features the manifest declares, by name.
fn declared_features() -> BTreeSet<String> {
    let Some(section) = section_of(MANIFEST, "[features]") else {
        return BTreeSet::new();
    };
    section
        .lines()
        .filter_map(|line| {
            let (name, _) = line.split_once('=')?;
            let name = name.trim();
            (!name.is_empty() && !name.starts_with('#')).then(|| name.to_owned())
        })
        .collect()
}

/// Every feature name the readme tells somebody to pass to cargo.
fn features_named_in(text: &str) -> BTreeSet<String> {
    let mut named = BTreeSet::new();
    let mut rest = text;
    while let Some(at) = rest.find("--features") {
        let after = &rest[at + "--features".len()..];
        if let Some(word) = after
            .split_whitespace()
            .next()
            .map(|word| word.trim_matches(|character: char| !character.is_alphanumeric()))
        {
            if !word.is_empty() {
                named.insert(word.to_owned());
            }
        }
        rest = after;
    }
    named
}

/// The value of a top-level manifest key, unquoted.
fn value_of(manifest: &str, key: &str) -> Option<String> {
    manifest.lines().find_map(|line| {
        let (name, value) = line.split_once('=')?;
        (name.trim() == key).then(|| value.trim().trim_matches('"').to_owned())
    })
}

/// The text from a heading or an opening bracket to the start of the next table.
///
/// Crude on purpose: the question is what a person opening the file would find
/// under that heading, and a parser would answer a different question.
///
/// The cut is the next table header and never a blank line. Cutting at a blank
/// line was tried and was wrong for exactly the reason this file exists: a
/// comment explaining a decision sits above the line it explains, with a blank
/// line before it, so the check stopped reading right before the thing it was
/// checking for and reported it missing while it was there.
fn section_of<'a>(text: &'a str, opening: &str) -> Option<&'a str> {
    let at = text.find(opening)?;
    let rest = &text[at..];
    let end = rest
        .match_indices("\n[")
        .map(|(offset, _)| offset)
        .find(|offset| *offset > 0)
        .unwrap_or(rest.len());
    Some(&rest[..end])
}

/// Every second-level heading, in the order they appear.
fn headings_of(text: &str) -> Vec<String> {
    text.lines()
        .filter(|line| line.starts_with("## "))
        .map(str::trim_end)
        .map(str::to_owned)
        .collect()
}