rust-lifetime-annotation-advisor

Decide whether a signature or type needs a lifetime at all, which one, and whether owning the data would make the lifetime disappear. Start from the three elision rules (most signatures need nothing), add a named lifetime only to express a real relationship ("the result borrows from text, not from sep"), and treat a struct that grows two or three lifetime parameters as a design smell: owning the data (String, Arc<str>, indices) usually costs one allocation and removes the lifetime from every caller. Four small std-only Rust programs in scripts/ read source text (they never build your crate) and report redundant, missing, unused and over-restrictive lifetimes with the corrected signature.

#Trigger Conditions

Activate this skill when the user:

• Hits error[E0106]: missing lifetime specifier, expected named lifetime parameter, E0621 explicit lifetime required in the type of, E0310 the parameter type T may not live long enough, E0392 lifetime parameter 'a is never used, E0700 hidden type for impl Trait captures lifetime, E0521 borrowed data escapes outside of, lifetime may not live long enough, E0597 does not live long enough, E0515, E0373
• Sees 'static demanded by tokio::spawn, thread::spawn, Box<dyn Trait> or dyn Any
• Asks "do I need <'a> here?", "why does my struct need a lifetime?", "String or &str or Cow?", "one lifetime or two?", "what does '_ mean?", "what does T: 'static mean?", "impl Trait + '_ vs use<'a>?"
• Designs a parser, tokenizer, iterator, view or config type that borrows input; or a struct that wants to own data and borrow from it at the same time (self-referential)
• Migrates to edition 2024 and sees impl_trait_overcaptures warnings or new borrow errors around -> impl Trait
• Uses HRTB (for<'a> Fn(&'a T)), GATs (type Item<'a> where Self: 'a), PhantomData, variance questions

#Workflow

1. LOCATE    -> Which item needs the lifetime: fn signature, struct field, impl header, trait object, impl Trait?
                Read the compiler's labels ('1, '2, "argument requires that ... is borrowed for 'static").
2. AUDIT     -> build once: for t in elision_check missing_lifetime static_bounds lifetime_smells; do
                  rustc -O --edition 2021 "$SKILL/scripts/$t.rs" -o "/tmp/$t"; done
                /tmp/missing_lifetime src/     (E0106/E0392 before compiling)   /tmp/elision_check src/
                /tmp/static_bounds src/        /tmp/lifetime_smells src/   (edition from Cargo.toml)
3. ELIDE     -> Apply the three elision rules (table below). If elision already gives the right answer,
                write nothing; use '_ where a path type hides a lifetime (Formatter<'_>, Cow<'_, str>).
4. DECIDE    -> Borrow or own? (decision table). Prefer owning in long-lived structs, async tasks, threads,
                caches and public APIs; borrow in short-lived views, parsers and hot loops.
5. ANNOTATE  -> One lifetime per independent source of borrowed data. Tie outputs only to the inputs they
                really borrow from. Spell out object lifetimes (dyn Trait + 'a) and captures (use<..>).
6. VERIFY    -> cargo check; cargo clippy (needless_lifetimes, extra_unused_lifetimes);
                each script with --strict exits 1 on findings (CI gate)

#Do You Need an Annotation? The Three Elision Rules

When none applies (two or more input lifetimes and no &self, or no input lifetime at all) the output needs a name: E0106. Elision never happens in struct/enum fields, static/const items default to 'static, and trait objects follow separate default object lifetime rules (Box<dyn T> = dyn T + 'static, &'a dyn T = dyn T + 'a).

#Borrow or Own?

Rule of thumb: borrow in functions, own in structs, unless the struct is a short-lived view created and dropped within one scope (parser over a file buffer, iterator, guard). Cloning a 40-byte string to delete a lifetime parameter from 30 call sites is almost always the right trade; profile before reintroducing borrows.

#Error -> Cause -> Fix

Full catalogue with failing and fixed code: elision-and-errors.md.

#Core Rules

Structs that borrow return data tied to the struct's lifetime, not to &self.

pub struct Parser<'a> {
    src: &'a str,
    pos: usize,
}

impl<'a> Parser<'a> {
    pub fn new(src: &'a str) -> Self {
        Self { src, pos: 0 }
    }

    // `&mut self` is a short borrow; the token borrows the *source* ('a), so callers can
    // keep tokens while calling next_token again. Never write `&'a mut self` here (LT007).
    pub fn next_token(&mut self) -> Option<&'a str> {
        let rest = self.src[self.pos..].trim_start();
        if rest.is_empty() {
            return None;
        }
        let start = self.src.len() - rest.len();
        let end = rest.find(char::is_whitespace).unwrap_or(rest.len());
        self.pos = start + end;
        Some(&rest[..end])
    }
}

fn main() {
    let text = String::from("let x = 1");
    let mut p = Parser::new(&text);
    let a = p.next_token();
    let b = p.next_token(); // fine: `a` borrows `text`, not `p`
    println!("{a:?} {b:?}");
}

One lifetime per independent source; tie outputs only where data flows.

// Result may be either input: one lifetime, the shorter of the two at the call site.
fn longest<'a>(a: &'a str, b: &'a str) -> &'a str {
    if a.len() >= b.len() { a } else { b }
}

// Result only borrows `text`: `sep` keeps its own elided lifetime and can be a temporary.
fn before<'a>(text: &'a str, sep: &str) -> &'a str {
    text.split(sep).next().unwrap_or(text)
}

Covariance means one lifetime usually suffices: &'long T coerces to &'short T. A second lifetime is needed when two borrows must be independent, typically behind &mut (invariant) or when returning one of them: struct Split<'text, 'pat> lets the caller drop the pattern while keeping pieces of the text.

Cow when you usually borrow; Arc<str> when you share; String when you just want it to compile.

use std::borrow::Cow;
use std::sync::Arc;

fn normalize(input: &str) -> Cow<'_, str> {
    if input.contains('\t') { Cow::Owned(input.replace('\t', "    ")) } else { Cow::Borrowed(input) }
}

#[derive(Clone)]
struct Label {
    name: Arc<str>, // clone is a refcount bump; no lifetime parameter
}

fn main() {
    let n = normalize("a\tb");
    let label = Label { name: Arc::from(&*n) };
    let copy = label.clone();
    assert_eq!(&*copy.name, "a    b");
}

Trait objects default to 'static in boxes; say + 'a when they borrow.

struct Filter<'a> {
    // Box<dyn Fn(&str) -> bool> would mean `+ 'static`: no closure capturing `pattern` by reference.
    predicate: Box<dyn Fn(&str) -> bool + 'a>,
}

impl<'a> Filter<'a> {
    fn new(pattern: &'a str) -> Self {
        Self { predicate: Box::new(move |line: &str| line.contains(pattern)) }
    }
}

T: 'static means "owns everything or borrows only 'static data", not "lives forever". String, Vec<u8>, Arc<Config> and &'static str are all 'static; &'a str and Vec<&'a str> are not. A 'static value can still be dropped at any time. Require it only where data truly escapes the caller's scope: thread::spawn, tokio::spawn, Box<dyn Any>, globals.

use std::fmt::Debug;
use std::thread;

fn log_later<T: Debug + Send + 'static>(value: T) -> thread::JoinHandle<()> {
    thread::spawn(move || println!("{value:?}")) // without 'static: E0310
}

fn log_now<T: Debug + ?Sized>(value: &T) {
    println!("{value:?}"); // only borrows: no 'static bound (LT009)
}

Return-position impl Trait: know what it captures. Edition 2021 captures type parameters but not lifetimes unless named (+ '_ or + use<'a>, else E0700). Edition 2024 captures every in-scope lifetime, so the result keeps arguments borrowed; opt out with precise capturing (Rust 1.82+), which must still list every type parameter in scope.

// Borrows `xs`: '_ (any edition) or use<'_> says so.
fn evens(xs: &[u32]) -> impl Iterator<Item = u32> + '_ {
    xs.iter().copied().filter(|x| x % 2 == 0)
}

// Owns its data: use<> lets callers drop `xs` while iterating (needed in edition 2024).
fn evens_owned(xs: &[u32]) -> impl Iterator<Item = u32> + use<> {
    xs.to_vec().into_iter().filter(|x| x % 2 == 0)
}

Self-referential structs do not exist in safe Rust. struct Doc { text: String, words: Vec<&'? str> } has no lifetime to write because moving Doc would move text. Store ranges (Vec<Range<usize>>), keep owner and view as two values (let doc = load(); let view = View::new(&doc);), use an arena, or a vetted crate (self_cell, ouroboros, yoke). See self-referential-and-escape-hatches.md.

#Advanced Quick Reference

Variance, HRTB, GATs, closures returning references and NLL limitations: advanced-lifetimes.md. Async and Send: async-lifetimes.md.

#Output Format

When advising, answer with:

1. Verdict - "no annotation needed (rule N)", "needs 'a on X and the return", or "own the data instead", with the elision rule or error code that decides it.
2. Signature/type - the exact corrected signature or struct definition, compiling as written; state the MSRV or edition when it relies on one (GATs 1.65, use<..> 1.82, edition 2024 = 1.85).
3. Why - one or two sentences on what the lifetime promises the caller ("the token borrows the source text, not the parser").
4. Cost of the alternative - when suggesting owned data: what is allocated/cloned and how often; when keeping borrows: which types and callers inherit the lifetime.
5. Verification - cargo check expectations and the script run (--strict) that now passes.

#Scripts

Small, standard-library-only Rust programs that read source text; they never compile or run your code. Build each once with rustc -O --edition 2021 scripts/<name>.rs -o /tmp/<name> (no Cargo project, no crates).

/tmp/missing_lifetime src/                           # files and/or directories (.rs, skips target/)
/tmp/elision_check src/parser.rs --json              # machine-readable findings with fix
cat lib.rs | /tmp/lifetime_smells - --edition 2024   # stdin (edition defaults to 2021 there)
/tmp/static_bounds src/ --strict                     # exit 1 on any finding (CI gate)
/tmp/lifetime_smells src/ --max-lifetimes 1          # LT010 threshold (default 2)
/tmp/elision_check src/ --select LT001 --ignore LT005
/tmp/missing_lifetime --list-rules                   # each script lists its rules with why and fix

The edition comes from the nearest Cargo.toml (--edition overrides; stdin defaults to 2021). The scanner is not a compiler: rules stay quiet when a path type might hide a lifetime, so a clean run is not a proof; cargo check is. Silence a deliberate case with // noqa: LT008 on the item's line. Exit codes: 0 clean (or findings without --strict), 1 findings with --strict, 2 usage error or unreadable file.

#Additional Resources