Suggest Tests Tool Internals and Contribution Guide

# Suggest tests tool This chapter is about the internals of and contribution instructions for the `suggest-tests` tool. For a high-level overview of the tool, see [this section](../building/suggested.md#x-suggest). This tool is currently in a beta state and is tracked by [this](https://github.com/rust-lang/rust/issues/109933) issue on Github. Currently the number of tests it will suggest are very limited in scope, we are looking to expand this (contributions welcome!). ## Internals The tool is defined in a separate crate ([`src/tools/suggest-tests`](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests)) which outputs suggestions which are parsed by a shim in bootstrap ([`src/bootstrap/src/core/build_steps/suggest.rs`](https://github.com/rust-lang/rust/blob/master/src/bootstrap/src/core/build_steps/suggest.rs)). The only notable thing the bootstrap shim does is (when invoked with the `--run` flag) use bootstrap's internal mechanisms to create a new `Builder` and uses it to invoke the suggested commands. The `suggest-tests` crate is where the fun happens, two kinds of suggestions are defined: "static" and "dynamic" suggestions. ### Static suggestions Defined [here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/static_suggestions.rs). Static suggestions are simple: they are just [globs](https://crates.io/crates/glob) which map to a `x` command. In `suggest-tests`, this is implemented with a simple `macro_rules` macro. ### Dynamic suggestions Defined [here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/dynamic_suggestions.rs). These are more complicated than static suggestions and are implemented as functions with the following signature: `fn(&Path) -> Vec<Suggestion>`. In other words, each suggestion takes a path to a modified file and (after running arbitrary Rust code) can return any number of suggestions, or none. Dynamic suggestions are useful for situations where fine-grained control over suggestions is needed. For example, modifications to the `compiler/xyz/` path should trigger the `x test compiler/xyz` suggestion. In the future, dynamic suggestions might even read file contents to determine if (what) tests should run. ## Adding a suggestion The following steps should serve as a rough guide to add suggestions to `suggest-tests` (very welcome!): 1. Determine the rules for your suggestion. Is it simple and operates only on a single path or does it match globs? Does it need fine-grained control over the resulting command or does "one size fit all"? 2. Based on the previous step, decide if your suggestion should be implemented as either static or dynamic. 3. Implement the suggestion. If it is dynamic then a test is highly recommended, to verify that your logic is correct and to give an example of the suggestion. See the [tests.rs](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/tests.rs) file. 4. Open a PR implementing your suggestion. **(TODO: add example PR)**

This section delves into the internal workings of the `suggest-tests` tool, which suggests tests to run based on code changes. It covers both static suggestions (simple glob-based mappings) and dynamic suggestions (more complex, function-based suggestions). The guide provides steps for contributing new suggestions, including determining the suggestion type (static or dynamic), implementing it, and adding tests, with a focus on expanding the tool's capabilities.