From 908196cce14ceb54b75ef4438281ee5519099031 Mon Sep 17 00:00:00 2001 From: Camilo Azula <4519631+camiloazula@users.noreply.github.com> Date: Thu, 5 Nov 2026 18:19:23 +0100 Subject: [PATCH] Give each crate a README of its own, compiled with the doctests Every crate showed the workspace README on crates.io, the front door's story told six more times. Each guard crate, the reader and core now carry a README that says what it reads, how to depend on it (through `milo-guards` and its feature, or on its own), its example and the contract, with absolute links so crates.io resolves them. The example is included in the crate's doctests like the front door's, so it cannot drift from the code. `milo-guards` keeps the workspace README, which is about it. Co-Authored-By: Claude Fable 5.1 --- CHANGELOG.md | 5 +++ crates/code/Cargo.toml | 2 +- crates/code/README.md | 85 ++++++++++++++++++++++++++++++++++++ crates/code/src/lib.rs | 11 +++++ crates/core/Cargo.toml | 2 +- crates/core/README.md | 64 +++++++++++++++++++++++++++ crates/core/src/lib.rs | 11 +++++ crates/file/Cargo.toml | 2 +- crates/file/README.md | 79 +++++++++++++++++++++++++++++++++ crates/file/src/lib.rs | 11 +++++ crates/secrets/Cargo.toml | 2 +- crates/secrets/README.md | 84 ++++++++++++++++++++++++++++++++++++ crates/secrets/src/lib.rs | 11 +++++ crates/shell/Cargo.toml | 2 +- crates/shell/README.md | 91 +++++++++++++++++++++++++++++++++++++++ crates/shell/src/lib.rs | 11 +++++ crates/url/Cargo.toml | 2 +- crates/url/README.md | 77 +++++++++++++++++++++++++++++++++ crates/url/src/lib.rs | 11 +++++ 19 files changed, 557 insertions(+), 6 deletions(-) create mode 100644 crates/code/README.md create mode 100644 crates/core/README.md create mode 100644 crates/file/README.md create mode 100644 crates/secrets/README.md create mode 100644 crates/shell/README.md create mode 100644 crates/url/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index faffb9e1..b4c17f93 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,11 @@ a caller is here, what it changes inside a guard is in the commits. ## Unreleased +- Each crate carries a README of its own (what it reads, how to depend on + it, its example, compiled with the doctests), where every crate showed the + workspace's; the front door `milo-guards` keeps that one. +- The README's logo is named by its absolute URL, so crates.io shows it. + ## 0.1.0 (2026-11-05) The first release, on crates.io as `milo-guards` with the guards behind it. diff --git a/crates/code/Cargo.toml b/crates/code/Cargo.toml index 1ba49bea..e7b9b0e0 100644 --- a/crates/code/Cargo.toml +++ b/crates/code/Cargo.toml @@ -7,7 +7,7 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -readme.workspace = true +readme = "README.md" keywords.workspace = true categories.workspace = true rust-version.workspace = true diff --git a/crates/code/README.md b/crates/code/README.md new file mode 100644 index 00000000..c017d108 --- /dev/null +++ b/crates/code/README.md @@ -0,0 +1,85 @@ +# milo-guards-code + +Reads Python and JavaScript code and says what it is certain to do to files +and what it runs, or that it does not understand it. Part of +[milo-guards](https://github.com/camiloazula/milo-guards); a reader, not a guard. + +A shell line can hand an interpreter code (`python3 -c`, `node -e`), and an +agent can write a script or run a snippet directly. What matters to a guard +is which files the code deletes, writes, reads and moves, and what it runs. +This crate reads Python and JavaScript (Node, Bun and Deno) with their own +tree-sitter grammars and answers two questions of a piece of code: + +- **What is it certain to do?** `read` gives the `Act`s the code makes, in + order: a delete, a write, a read, a move, a program started, an + environment changed, each with the paths it names. What the reader cannot + follow comes out as `Act::Unread`, never left out. +- **Does it understand the code?** `understand` holds the code to a strict + allow-list: a few plain statements whose every call, name and import is on + a short list that only computes. Anything else is + `Understanding::NotUnderstood`, and a caller must not take "no acts" for + "does nothing" for such code. + +The reader judges nothing. Whether a delete of a path is risky is the +caller's: the shell guard of milo-guards turns an act into what it already +judges (a delete is `rm -rf PATH`, a command line a script a shell reads). + +## Install + +Through the front door, where it is the `code` feature (on by default) and +what the shell guard reads inline code with: + +```toml +[dependencies] +milo-guards = "0.1" +``` + +Or on its own: + +```toml +[dependencies] +milo-guards-code = "0.1" +``` + +If your program also links tree-sitter, it has to be on the 0.26 runtime: +tree-sitter allows one version per lockfile. + +## Example + +```rust +use milo_guards_code::{read, understand, Act, Arg, Language, Understanding}; + +// A snippet that computes is understood, and does nothing to a file. +let code = "print(1 + 1)"; +assert!(read(Language::Python, code).acts.is_empty()); +assert_eq!( + understand(Language::Python, code), + Understanding::Understood { imports: true }, +); + +// A delete is an act with the path it names, kept whatever the code is. +let code = "import shutil\nshutil.rmtree('/home/me')"; +let reading = read(Language::Python, code); +assert!(matches!(&reading.acts[..], [Act::Remove(Arg::Known(path))] if path == "/home/me")); +assert_eq!(understand(Language::Python, code), Understanding::NotUnderstood); + +// A name only known when the code runs is an argument it does not know. +let reading = read(Language::JavaScript, "require('fs').rmSync(process.argv[1])"); +assert!(matches!(&reading.acts[..], [Act::Remove(Arg::Unknown(_))])); +``` + +## Contract + +Like every milo-guards crate: no I/O and no environment reads, deterministic +(the same input gives the same answer on every machine), no policy (it +reports, and what to do with a finding is the caller's), what cannot be read +is risky, and nothing it is given makes it panic. The rules are on the +repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md). + +## License + +MIT or Apache-2.0, at your option +([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT), +[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of +[milo-guards](https://github.com/camiloazula/milo-guards); the API is on +[docs.rs](https://docs.rs/milo-guards-code). diff --git a/crates/code/src/lib.rs b/crates/code/src/lib.rs index aa86bab6..0cf76160 100644 --- a/crates/code/src/lib.rs +++ b/crates/code/src/lib.rs @@ -1000,3 +1000,14 @@ pub(crate) fn loads(specifier: &str, code: &str) -> Option { Foreign::Outside => Act::Loads(shorten(code)), }) } + +/// The README's example, compiled and run with the doctests so it cannot +/// drift from the code. Only rustdoc's doctest pass reads the file, so +/// building this crate never needs the README. +#[cfg(doctest)] +#[allow( + clippy::disallowed_macros, + reason = "the README include is read by rustdoc's doctest pass only" +)] +#[doc = include_str!("../README.md")] +mod readme {} diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml index 7ada5e3d..5817e3af 100644 --- a/crates/core/Cargo.toml +++ b/crates/core/Cargo.toml @@ -7,7 +7,7 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -readme.workspace = true +readme = "README.md" keywords.workspace = true categories.workspace = true rust-version.workspace = true diff --git a/crates/core/README.md b/crates/core/README.md new file mode 100644 index 00000000..1db87e3f --- /dev/null +++ b/crates/core/README.md @@ -0,0 +1,64 @@ +# milo-guards-core + +What every guard of [milo-guards](https://github.com/camiloazula/milo-guards) shares: the verdict types, the path +model and the test kit. + +A guard reads what an agent is about to do and says whether it is safe to do +without asking, or risky and why. This crate holds the parts of that which do +not depend on what is being read: + +- **The verdict.** `Assessment` is `Safe`, or `Risky` with a `Finding` for + each reason. A finding names a rule of the guard's own enum (which + implements `RuleName`, with a stable wire name), the reason in words, the + target it is about, and where there is one, what to do instead. +- **The directories everything is judged against.** `Paths`: the working + directory, the home directory and the workspace folders, with the files + the caller gates (`Protected`). +- **The path model.** `Resolver` says where a path spelled out as text lands + (`Place`), by its spelling alone, for POSIX and Windows (`Flavour`), on + whatever host it runs. +- **For guard crates**, helpers that take a path's spelling apart + (`spelling`), and behind the `testing` feature the table checker and the + sample directories the guards test themselves with. + +It depends on nothing beyond `std`, and does no I/O. + +## Install + +A caller of the guards depends on [`milo-guards`](https://docs.rs/milo-guards), +which re-exports this crate's types; depend on this crate directly only to +write a guard of your own. + +```toml +[dependencies] +milo-guards-core = "0.1" +``` + +## Example + +```rust +use milo_guards_core::{Flavour, Paths, Place, Resolver, Spelling}; + +let paths = Paths::new("/home/me/work/repo", "/home/me", ["/home/me/work/repo"]); +let resolver = Resolver::new(&paths); +let place = |path| resolver.place(Spelling::Plain(path), Flavour::Posix); +assert_eq!(place("src/../target"), Place::Inside); +assert_eq!(place("/home/me"), Place::Home { exact: true }); +assert_eq!(place("/etc/hosts"), Place::Top("a system folder")); +``` + +## Contract + +Like every milo-guards crate: no I/O and no environment reads, deterministic +(the same input gives the same answer on every machine), no policy (it +reports, and what to do with a finding is the caller's), what cannot be read +is risky, and nothing it is given makes it panic. The rules are on the +repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md). + +## License + +MIT or Apache-2.0, at your option +([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT), +[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of +[milo-guards](https://github.com/camiloazula/milo-guards); the API is on +[docs.rs](https://docs.rs/milo-guards-core). diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index cbaea40d..66a592f1 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -44,3 +44,14 @@ pub use paths::{Paths, Protected, ProtectedKind}; pub use place::{Place, Sensitivity}; pub use resolve::{Flavour, Resolver, Spelling}; pub use verdict::{Assessment, Finding, RuleName}; + +/// The README's example, compiled and run with the doctests so it cannot +/// drift from the code. Only rustdoc's doctest pass reads the file, so +/// building this crate never needs the README. +#[cfg(doctest)] +#[allow( + clippy::disallowed_macros, + reason = "the README include is read by rustdoc's doctest pass only" +)] +#[doc = include_str!("../README.md")] +mod readme {} diff --git a/crates/file/Cargo.toml b/crates/file/Cargo.toml index 78443d12..83e9990a 100644 --- a/crates/file/Cargo.toml +++ b/crates/file/Cargo.toml @@ -7,7 +7,7 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -readme.workspace = true +readme = "README.md" keywords.workspace = true categories.workspace = true rust-version.workspace = true diff --git a/crates/file/README.md b/crates/file/README.md new file mode 100644 index 00000000..3379db8b --- /dev/null +++ b/crates/file/README.md @@ -0,0 +1,79 @@ +# milo-guards-file + +Judges one read or write of a path through a file API and says whether it is +safe without asking, or risky and why. The file guard of +[milo-guards](https://github.com/camiloazula/milo-guards). + +A shell line shows what a shell is about to do; an agent also reads and +writes files through a file API, and no line shows those calls. This guard +takes the two things such a call has, an `Access` and the path as the agent +wrote it, and judges them: `judge`. + +The path is one literal path, resolved by its spelling alone against the +`Paths` the caller passes: relative to the working directory, `~` as the home +directory, `..` applied, and the Windows spellings (drives, shares, long +paths, short names, any case) read as Windows reads them, whatever host the +guard runs on. Nothing is read from the disk, so a symlink is judged by its +own name. + +- A **read** is safe wherever it lands, except a key or a credential + (`read_secret`). An agent reads widely, and reading is what a caller lets + run unasked. +- A **write** (an edit, a create, an append, a rename's target) is safe + inside a workspace folder, to a temporary file and to the null device. + Anywhere else is a finding: beyond the workspace (`write_outside`), to a + key, a startup file, a file a tool runs on its own or the repository's + history (`write_sensitive`), or to what the caller gates + (`write_protected`). +- A path that is not one literal path, or that cannot be placed, is + `unreadable`; one on another machine is `network_share`. + +## Install + +Through the front door, where it is the `file` feature (on by default): + +```toml +[dependencies] +milo-guards = "0.1" +``` + +Or on its own: + +```toml +[dependencies] +milo-guards-file = "0.1" +``` + +## Example + +```rust +use milo_guards_file::{judge, Access, Paths, Rule}; + +let paths = Paths::new("/home/me/work/repo", "/home/me", ["/home/me/work/repo"]); + +assert!(judge(Access::Read, "src/main.rs", &paths).is_safe()); +assert!(judge(Access::Write, "src/main.rs", &paths).is_safe()); + +let assessment = judge(Access::Read, "~/.ssh/id_ed25519", &paths); +assert_eq!(assessment.findings()[0].rule, Rule::ReadSecret); +assert_eq!(assessment.findings()[0].reason, "reads your SSH keys"); + +let assessment = judge(Access::Write, "../other/x", &paths); +assert_eq!(assessment.findings()[0].rule, Rule::WriteOutside); +``` + +## Contract + +Like every milo-guards crate: no I/O and no environment reads, deterministic +(the same input gives the same answer on every machine), no policy (it +reports, and what to do with a finding is the caller's), what cannot be read +is risky, and nothing it is given makes it panic. The rules are on the +repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md). + +## License + +MIT or Apache-2.0, at your option +([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT), +[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of +[milo-guards](https://github.com/camiloazula/milo-guards); the API is on +[docs.rs](https://docs.rs/milo-guards-file). diff --git a/crates/file/src/lib.rs b/crates/file/src/lib.rs index 398918a2..ae39f1fb 100644 --- a/crates/file/src/lib.rs +++ b/crates/file/src/lib.rs @@ -343,3 +343,14 @@ fn has_variable(path: &str) -> bool { _ => false, }) } + +/// The README's example, compiled and run with the doctests so it cannot +/// drift from the code. Only rustdoc's doctest pass reads the file, so +/// building this crate never needs the README. +#[cfg(doctest)] +#[allow( + clippy::disallowed_macros, + reason = "the README include is read by rustdoc's doctest pass only" +)] +#[doc = include_str!("../README.md")] +mod readme {} diff --git a/crates/secrets/Cargo.toml b/crates/secrets/Cargo.toml index 4fd7ea52..64ebfc9b 100644 --- a/crates/secrets/Cargo.toml +++ b/crates/secrets/Cargo.toml @@ -7,7 +7,7 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -readme.workspace = true +readme = "README.md" keywords.workspace = true categories.workspace = true rust-version.workspace = true diff --git a/crates/secrets/README.md b/crates/secrets/README.md new file mode 100644 index 00000000..fb86ec6e --- /dev/null +++ b/crates/secrets/README.md @@ -0,0 +1,84 @@ +# milo-guards-secrets + +Reads a text and says whether it holds a credential (a key, a token, a +password) or personal data, and where. The secrets guard of +[milo-guards](https://github.com/camiloazula/milo-guards). + +A caller that puts text in front of a model scrubs it first, and a caller +that lets an agent write a source file asks whether the content carries a key +into it. Both are the same question of a text: what in it is a secret. The +text has no place, so unlike the guards that judge a path there is no `Paths` +here: a text in, findings out. + +- **A finding never carries the secret.** Its target is masked: the public + prefix of a key and its length (`AKIA… (20 chars)`), only the length when + what was found begins with the secret itself, or the first line of a block + of private key. +- **The spans are offsets, not text.** `find_spans` gives the byte range of + each thing found, on character boundaries, so a caller can replace it and + leave the text around it as it was. +- **The table is judged by shape and by value.** A key is found by the prefix + and the length its provider publishes; a password only where a name says + so; a number only when it passes its own check (the Luhn check of a card). +- **A text that is no key is safe.** SHAs, UUIDs, base64 fixtures, hashes, + minified code and a lockfile's integrity hashes are safe. +- **Shapeless secrets are a second function**, `find_high_entropy`, never a + part of `find`: a guard has no modes, and a caller that wants a guess calls + it. + +The text is read in time linear in its length, whatever it holds. + +## Install + +Through the front door, where it is the `secrets` feature (opt in: most +callers want the other guards and not a table of credential patterns in +their binary): + +```toml +[dependencies] +milo-guards = { version = "0.1", features = ["secrets"] } +``` + +Or on its own: + +```toml +[dependencies] +milo-guards-secrets = "0.1" +``` + +## Example + +```rust +use milo_guards_secrets::{find, find_spans, Rule}; + +assert!(find("let sha = \"3f786850e387550fdab836ed7e6dc881de23001b\";").is_safe()); + +// `AKIA` and sixteen characters: an AWS access key. +let text = format!("key = {}", ["AKIA", "FAKE2KEY3ID4TEST"].concat()); +let assessment = find(&text); +let finding = &assessment.findings()[0]; +assert_eq!(finding.rule, Rule::CloudKey); +assert_eq!(finding.reason, "holds an AWS access key"); +assert_eq!(finding.target.as_deref(), Some("AKIA… (20 chars)")); + +// A caller that scrubs replaces the span, and nothing else. +let span = find_spans(&text)[0]; +assert_eq!((span.rule, span.start, span.end), (Rule::CloudKey, 6, 26)); +assert_eq!(format!("{}[hidden]{}", &text[..span.start], &text[span.end..]), "key = [hidden]"); +``` + +## Contract + +Like every milo-guards crate: no I/O and no environment reads, deterministic +(the same input gives the same answer on every machine), no policy (it +reports, and what to do with a finding is the caller's), what cannot be read +is risky, and nothing it is given makes it panic. The rules are on the +repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md). + +## License + +MIT or Apache-2.0, at your option +([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT), +[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of +[milo-guards](https://github.com/camiloazula/milo-guards); the API is on +[docs.rs](https://docs.rs/milo-guards-secrets). diff --git a/crates/secrets/src/lib.rs b/crates/secrets/src/lib.rs index f6fae8b4..fb4cdd5c 100644 --- a/crates/secrets/src/lib.rs +++ b/crates/secrets/src/lib.rs @@ -273,3 +273,14 @@ pub fn find_high_entropy(text: &str, bits: f64) -> Vec { }) .collect() } + +/// The README's example, compiled and run with the doctests so it cannot +/// drift from the code. Only rustdoc's doctest pass reads the file, so +/// building this crate never needs the README. +#[cfg(doctest)] +#[allow( + clippy::disallowed_macros, + reason = "the README include is read by rustdoc's doctest pass only" +)] +#[doc = include_str!("../README.md")] +mod readme {} diff --git a/crates/shell/Cargo.toml b/crates/shell/Cargo.toml index 5675b02d..506af1df 100644 --- a/crates/shell/Cargo.toml +++ b/crates/shell/Cargo.toml @@ -7,7 +7,7 @@ edition.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -readme.workspace = true +readme = "README.md" keywords.workspace = true categories.workspace = true rust-version.workspace = true diff --git a/crates/shell/README.md b/crates/shell/README.md new file mode 100644 index 00000000..ddbc77c5 --- /dev/null +++ b/crates/shell/README.md @@ -0,0 +1,91 @@ +# milo-guards-shell + +Reads a shell command line (POSIX shell, PowerShell or cmd) and says whether +it is safe to run without asking, or risky and why. The shell guard of +[milo-guards](https://github.com/camiloazula/milo-guards). + +It works in three steps: + +1. **Split** the line into units, one per program it runs, with the grammar + of the shell that runs it (`Shell`). Chains, pipes, substitutions, loops + and blocks are walked, every branch whether or not it would run; wrappers + (`sudo`, `env`, `xargs`, `find -exec`) are taken off, and a shell started + with a script (`bash -c`, `eval`, `cmd /c`, `powershell -Command`) has + that script split in its own grammar. Python and JavaScript given inline + (`python3 -c`, `node -e`, a here-document) are read with their own + grammars, through `milo-guards-code`. +2. **Detect** with rules that read a unit's program, flags, operands and + redirects, never the raw text, and judge each path by where it resolves + against the `Paths` the caller passes. +3. **Combine**: the line is safe only when no unit is risky, and a risky line + carries every finding. + +Three functions answer three questions of the same reading: `classify`, +whether the line is safe; `effect`, whether it only reads (and whether the +reads stay in the workspace), changes something, or cannot be told; and +`explain`, how the line was read, unit by unit, drawn as a short tree for a +person to see. + +What cannot be read is risky: a program or a script known only when it runs, +a line the grammar cannot parse, shells nested past a limit. Nothing here +touches the file system or the environment: a Windows line is judged on macOS +as it would be on Windows. + +## Install + +Through the front door, where it is the `shell` feature (on by default): + +```toml +[dependencies] +milo-guards = "0.1" +``` + +Or on its own: + +```toml +[dependencies] +milo-guards-shell = "0.1" +``` + +The `inline` feature (on by default) reads the Python and JavaScript a line +gives an interpreter; off, such a line is still found but none of its code is +read, every inline line is `unknown`, and neither grammar is built. If your +program also links tree-sitter, it has to be on the 0.26 runtime. + +## Example + +```rust +use milo_guards_shell::{classify, effect, Effect, Paths, Reach, Rule, Shell}; + +let paths = Paths::new("/home/me/work/repo", "/home/me", ["/home/me/work/repo"]); + +// Building inside the workspace is the agent's own business. +assert!(classify("cargo build && rm -rf target", Shell::Posix, &paths).is_safe()); + +// Deleting the home directory is not, and the answer says why. +let assessment = classify("rm -rf ~", Shell::Posix, &paths); +let finding = &assessment.findings()[0]; +assert_eq!(finding.rule, Rule::Delete); +assert_eq!(finding.target.as_deref(), Some("~")); + +// Whether a line only reads is a second answer, from the same split. +assert_eq!(effect("git status", Shell::Posix, &paths), Effect::ReadsOnly(Reach::Workspace)); +assert_eq!(effect("mkdir build", Shell::Posix, &paths), Effect::Changes); +assert_eq!(effect("./script.sh", Shell::Posix, &paths), Effect::Unknown); +``` + +## Contract + +Like every milo-guards crate: no I/O and no environment reads, deterministic +(the same input gives the same answer on every machine), no policy (it +reports, and what to do with a finding is the caller's), what cannot be read +is risky, and nothing it is given makes it panic. The rules are on the +repository's [guidelines](https://github.com/camiloazula/milo-guards/blob/main/GUIDELINES.md). + +## License + +MIT or Apache-2.0, at your option +([LICENSE-MIT](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-MIT), +[LICENSE-APACHE](https://github.com/camiloazula/milo-guards/blob/main/LICENSE-APACHE)). Part of +[milo-guards](https://github.com/camiloazula/milo-guards); the API is on +[docs.rs](https://docs.rs/milo-guards-shell). diff --git a/crates/shell/src/lib.rs b/crates/shell/src/lib.rs index 682d1dad..c95e22f3 100644 --- a/crates/shell/src/lib.rs +++ b/crates/shell/src/lib.rs @@ -472,3 +472,14 @@ pub fn effect_paths(command: &str, shell: Shell, paths: &Paths) -> Option, findings: &mut Vec) -> bool { } ipv4 } + +/// The README's example, compiled and run with the doctests so it cannot +/// drift from the code. Only rustdoc's doctest pass reads the file, so +/// building this crate never needs the README. +#[cfg(doctest)] +#[allow( + clippy::disallowed_macros, + reason = "the README include is read by rustdoc's doctest pass only" +)] +#[doc = include_str!("../README.md")] +mod readme {}