Rename Red Knot (#17820)

crates/ty/docs/mypy_primer.md

@@ -0,0 +1,60 @@
+# Running `mypy_primer`
+
+## Basics
+
+`mypy_primer` can be run using `uvx --from "…" mypy_primer`. For example, to see the help message, run:
+
+```sh
+uvx --from "git+https://github.com/hauntsaninja/mypy_primer" mypy_primer -h
+```
+
+Alternatively, you can install the forked version of `mypy_primer` using:
+
+```sh
+uv tool install "git+https://github.com/hauntsaninja/mypy_primer"
+```
+
+and then run it using `uvx mypy_primer` or just `mypy_primer`, if your `PATH` is set up accordingly (see: [Tool executables]).
+
+## Showing the diagnostics diff between two Git revisions
+
+To show the diagnostics diff between two Git revisions (e.g. your feature branch and `main`), run:
+
+```sh
+mypy_primer \
+    --type-checker ty \
+    --old origin/main \
+    --new my/feature \
+    --debug \
+    --output concise \
+    --project-selector '/black$'
+```
+
+This will show the diagnostics diff for the `black` project between the `main` branch and your `my/feature` branch. To run the
+diff for all projects we currently enable in CI, use `--project-selector "/($(paste -s -d'|' crates/ty_python_semantic/resources/primer/good.txt))\$"`.
+
+You can also take a look at the [full list of ecosystem projects]. Note that some of them might still need a `ty_paths` configuration
+option to work correctly.
+
+## Avoiding recompilation
+
+If you want to run `mypy_primer` repeatedly, e.g. for different projects, but for the same combination of `--old` and `--new`, you
+can use set the `MYPY_PRIMER_NO_REBUILD` environment variable to avoid recompilation of ty:
+
+```sh
+MYPY_PRIMER_NO_REBUILD=1 mypy_primer …
+```
+
+## Running from a local copy of the repository
+
+If you are working on a local branch, you can use `mypy_primer`'s `--repo` option to specify the path to your local copy of the `ruff` repository.
+This allows `mypy_primer` to check out local branches:
+
+```sh
+mypy_primer --repo /path/to/ruff --old origin/main --new my/local-branch …
+```
+
+Note that you might need to clean up `/tmp/mypy_primer` in order for this to work correctly.
+
+[full list of ecosystem projects]: https://github.com/hauntsaninja/mypy_primer/blob/master/mypy_primer/projects.py
+[tool executables]: https://docs.astral.sh/uv/concepts/tools/#tool-executables

crates/ty/docs/tracing.md

@@ -0,0 +1,128 @@
+# Tracing
+
+Traces are a useful tool to narrow down the location of a bug or, at least, to understand why the compiler is doing a particular thing.
+Note, tracing messages with severity `debug` or greater are user-facing. They should be phrased accordingly.
+Tracing spans are only shown when using `-vvv`.
+
+## Verbosity levels
+
+The CLI supports different verbosity levels.
+
+- default: Only show errors and warnings.
+- `-v` activates `info!`: Show generally useful information such as paths of configuration files, detected platform, etc., but it's not a lot of messages, it's something you'll activate in CI by default. cargo build e.g. shows you which packages are fresh.
+- `-vv` activates `debug!` and timestamps: This should be enough information to get to the bottom of bug reports. When you're processing many packages or files, you'll get pages and pages of output, but each line is link to a specific action or state change.
+- `-vvv` activates `trace!` (only in debug builds) and shows tracing-spans: At this level, you're logging everything. Most of this is wasted, it's really slow, we dump e.g. the entire resolution graph. Only useful to developers, and you almost certainly want to use `TY_LOG` to filter it down to the area your investigating.
+
+## Better logging with `TY_LOG` and `RAYON_NUM_THREADS`
+
+By default, the CLI shows messages from the `ruff` and `ty` crates. Tracing messages from other crates are not shown.
+The `TY_LOG` environment variable allows you to customize which messages are shown by specifying one
+or more [filter directives](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives).
+
+The `RAYON_NUM_THREADS` environment variable, meanwhile, can be used to control the level of concurrency ty uses.
+By default, ty will attempt to parallelize its work so that multiple files are checked simultaneously,
+but this can result in a confused logging output where messages from different threads are intertwined.
+To switch off concurrency entirely and have more readable logs, use `RAYON_NUM_THREADS=1`.
+
+### Examples
+
+#### Show all debug messages
+
+Shows debug messages from all crates.
+
+```bash
+TY_LOG=debug
+```
+
+#### Show salsa query execution messages
+
+Show the salsa `execute: my_query` messages in addition to all ty messages.
+
+```bash
+TY_LOG=ruff=trace,ty=trace,salsa=info
+```
+
+#### Show typing traces
+
+Only show traces for the `ty_python_semantic::types` module.
+
+```bash
+TY_LOG="ty_python_semantic::types"
+```
+
+Note: Ensure that you use `-vvv` to see tracing spans.
+
+#### Show messages for a single file
+
+Shows all messages that are inside of a span for a specific file.
+
+```bash
+TY_LOG=ty[{file=/home/micha/astral/test/x.py}]=trace
+```
+
+**Note**: Tracing still shows all spans because tracing can't know at the time of entering the span
+whether one if its children has the file `x.py`.
+
+**Note**: Salsa currently logs the entire memoized values. In our case, the source text and parsed AST.
+This very quickly leads to extremely long outputs.
+
+## Tracing and Salsa
+
+Be mindful about using `tracing` in Salsa queries, especially when using `warn` or `error` because it isn't guaranteed
+that the query will execute after restoring from a persistent cache. In which case the user won't see the message.
+
+For example, don't use `tracing` to show the user a message when generating a lint violation failed
+because the message would only be shown when linting the file the first time, but not on subsequent analysis
+runs or when restoring from a persistent cache. This can be confusing for users because they
+don't understand why a specific lint violation isn't raised. Instead, change your
+query to return the failure as part of the query's result or use a Salsa accumulator.
+
+## Tracing in tests
+
+You can use `ruff_db::testing::setup_logging` or `ruff_db::testing::setup_logging_with_filter` to set up logging in tests.
+
+```rust
+use ruff_db::testing::setup_logging;
+
+#[test]
+fn test() {
+  let _logging = setup_logging();
+
+  tracing::info!("This message will be printed to stderr");
+}
+```
+
+Note: Most test runners capture stderr and only show its output when a test fails.
+
+Note also that `setup_logging` only sets up logging for the current thread because [`set_global_default`](https://docs.rs/tracing/latest/tracing/subscriber/fn.set_global_default.html) can only be
+called **once**.
+
+## Release builds
+
+`trace!` events are removed in release builds.
+
+## Profiling
+
+ty generates a folded stack trace to the current directory named `tracing.folded` when setting the environment variable `TY_LOG_PROFILE` to `1` or `true`.
+
+```bash
+TY_LOG_PROFILE=1 ty -- --current-directory=../test -vvv
+```
+
+You can convert the textual representation into a visual one using `inferno`.
+
+```shell
+cargo install inferno
+```
+
+```shell
+# flamegraph
+cat tracing.folded | inferno-flamegraph > tracing-flamegraph.svg
+
+# flamechart
+cat tracing.folded | inferno-flamegraph --flamechart > tracing-flamechart.svg
+```
+
+![Example flamegraph](./tracing-flamegraph.png)
+
+See [`tracing-flame`](https://crates.io/crates/tracing-flame) for more details.