docs(contributing): document Rust toolchain and git-hook tooling (#12875)

* docs(contributing): document Rust toolchain and git-hook tooling

Rust is now the primary language in this repository, but the root
CONTRIBUTING.md only covered the TypeScript setup. Add a "Rust toolchain
and git hooks" section under "Setting Up the Environment" that covers
rustup and the pinned toolchain, just, the just init tools, and the
dylint tools.

Two things that are easy to get wrong and cost real debugging time:

- cargo-dylint and dylint-link must be installed from source, not with
  cargo binstall. The prebuilt binaries reference the dylint_driver
  crate at the path where they were built, so building the per-toolchain
  driver fails locally with an error pointing at a nonexistent
  .../dylint/driver directory.
- ~/.cargo/bin must be on PATH (ahead of any system Rust in /usr/bin),
  because the pre-push hook locates its tools through PATH and silently
  skips a Rust check when the tool is missing rather than failing, so a
  push that looks clean locally can still fail format, doc, or dylint in
  CI.

Point pacquet/CONTRIBUTING.md at the new root section instead of
repeating the tool list, and correct its cargo binstall advice for the
dylint tools.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: correct dylint install hint in justfile and pre-push hook

The `just dylint` recipe comment and the pre-push hook's skip message
both told contributors to install cargo-dylint via `cargo binstall`,
which produces a prebuilt binary that fails to build the per-toolchain
driver locally. Point both at `cargo install` from source, matching the
CONTRIBUTING.md guidance.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CONTRIBUTING.md

@@ -3,6 +3,8 @@
 ## Table of contents
 
 - [Setting Up the Environment](#setting-up-the-environment)
+  - [JavaScript and TypeScript CLI](#javascript-and-typescript-cli)
+  - [Rust toolchain and git hooks](#rust-toolchain-and-git-hooks)
 - [Working with Git Worktrees](#working-with-git-worktrees)
 - [Running Tests](#running-tests)
 - [Submitting a Pull Request (PR)](#submitting-a-pull-request-pr)
@@ -19,6 +21,10 @@
 
 ## Setting Up the Environment
 
+The repository holds two implementations of the same package manager: the TypeScript pnpm CLI and the Rust `pacquet` port (plus the Rust `pnpr` registry server). Most contributions touch Rust, but the two stacks share one workspace, so set up both.
+
+### JavaScript and TypeScript CLI
+
 1. Run `pnpm install` in the root of the repository to install all dependencies.
 1. Run `pnpm add ./pnpm/dev -g` to make pnpm from the repository available in the command line via the `pd` command.
 1. Run `pnpm run compile` to create an initial build of pnpm from the source in the repository.
@@ -32,6 +38,32 @@ Some of the e2e tests run node-gyp, so you might need to install some build-esse
 sudo dnf install make automake gcc gcc-c++ kernel-devel
 ```
 
+### Rust toolchain and git hooks
+
+Rust is now the primary language in this repository, so most contributions need a working Rust toolchain and the Rust developer tools. The Rust workspace (`Cargo.toml`, `rust-toolchain.toml`, `justfile`) lives at the repository root; run `cargo` and `just` from there.
+
+1. Install [`rustup`](https://rustup.rs). You do not need to select a toolchain by hand. `rust-toolchain.toml` pins the version the project builds with, and `rustup` installs it, together with `rustfmt` and `clippy` from the pinned `default` profile, the first time you run `cargo` inside the repository.
+
+2. Install [`just`](https://just.systems) (the task runner) and [`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall), then install the task tools from the repository root:
+
+   ```shell
+   just init
+   ```
+
+   `just init` installs `cargo-nextest`, `cargo-watch`, `cargo-insta`, `typos-cli`, `taplo-cli`, `wasm-pack`, and `cargo-llvm-cov`.
+
+3. Install the dylint tools, which `just init` does not cover, **from source**:
+
+   ```shell
+   cargo install cargo-dylint dylint-link
+   ```
+
+   Install these from source rather than with `cargo binstall`. The prebuilt `cargo-dylint` binaries reference the `dylint_driver` crate at the path where they were built, so building the per-toolchain driver fails locally with an error that points at a nonexistent `.../dylint/driver` directory. A `cargo install` build resolves the driver against your local cargo registry and works.
+
+Make sure `~/.cargo/bin` is on your `PATH`, ahead of any system-wide Rust in `/usr/bin`. `rustup`'s installer adds this entry through `~/.cargo/env`; ensure your shell sources it. This matters for the git hooks. The `pnpm install` step above wires up husky, and its `pre-push` hook runs the Rust checks in `pacquet/scripts/pre-push-rust.sh` (format, doc, dylint) alongside the TypeScript compile and lint. That script locates `cargo`, `rustup`, `taplo`, and `cargo-dylint` through `PATH`, and it **skips** a check when the tool is not found rather than failing. A push that appears to pass locally with the tools off `PATH` has silently skipped the format, doc, and dylint checks, so those problems surface only in CI.
+
+For the full Rust development workflow (checks, tests, benchmarks, and the code style guide), see [`pacquet/CONTRIBUTING.md`](./pacquet/CONTRIBUTING.md).
+
 ## Working with Git Worktrees
 
 Worktrees let you check out multiple branches simultaneously in separate directories,

justfile

@@ -74,8 +74,9 @@ lint:
   cargo clippy --locked --workspace --all-targets -- --deny warnings
 
 # Run perfectionist dylint rules. Requires `cargo-dylint` and `dylint-link`
-# (install with `cargo binstall cargo-dylint dylint-link`). The lint library
-# is pinned in `dylint.toml`.
+# (install from source with `cargo install cargo-dylint dylint-link`; the
+# prebuilt binstall binaries fail to build the driver locally). The lint
+# library is pinned in `dylint.toml`.
 dylint:
   env RUSTFLAGS="-D warnings" cargo dylint --all -- --all-targets --workspace
 

pacquet/CONTRIBUTING.md

@@ -57,7 +57,7 @@ If perfectionist flags code that is actually correct, or fails to flag code its
 
 The same procedure applies when a perfectionist rule itself is wrong — for example, a rule that flags an idiom the rule's documentation says it should permit. Silence the site with `#[expect(..., reason = "...")]`, link the upstream issue from the `reason` if one already exists, and file the issue if it does not. Do not edit `dylint.toml` to globally disable a rule, and do not pin perfectionist to an older `tag` to dodge a finding.
 
-You can run the same check locally with `just dylint` (requires `cargo-dylint` and `dylint-link`; install with `cargo binstall cargo-dylint dylint-link`).
+You can run the same check locally with `just dylint`. It requires `cargo-dylint` and `dylint-link`, which `just init` does not install; install them from source as described under [Rust toolchain and git hooks](../CONTRIBUTING.md#rust-toolchain-and-git-hooks) in the root guide.
 
 ## Setup
 
@@ -72,6 +72,8 @@ Install these first:
 - [`pnpm`](https://pnpm.io)
 - `git`
 
+The repository root [`CONTRIBUTING.md`](../CONTRIBUTING.md#rust-toolchain-and-git-hooks) covers the Rust toolchain and the tools the git hooks need, including a note on why `cargo-dylint` must be installed from source and why `~/.cargo/bin` has to be on your `PATH`. Read it first, then use the pacquet-specific steps below.
+
 ### Install
 
 Install the project's task tools and the git pre-push hook:
@@ -82,6 +84,8 @@ just init
 
 `just init` invokes `cargo-binstall` to install `cargo-nextest`, `cargo-watch`, `cargo-insta`, `typos-cli`, `taplo-cli`, `wasm-pack`, and `cargo-llvm-cov`. The repo-wide `pnpm install` wires up husky, whose `pre-push` hook runs `pacquet/scripts/pre-push-rust.sh` (format, doc, dylint) alongside the TypeScript compile and lint checks.
 
+`just init` does not install the dylint tools. To run the `Dylint` job's checks locally, install `cargo-dylint` and `dylint-link` as described under [Rust toolchain and git hooks](../CONTRIBUTING.md#rust-toolchain-and-git-hooks) in the root guide.
+
 Install the test dependencies:
 
 ```sh

pacquet/scripts/pre-push-rust.sh

@@ -38,7 +38,7 @@ if command -v cargo >/dev/null 2>&1; then
             failed=1
         fi
     else
-        yellow '! cargo-dylint not found on PATH — skipping dylint check (install with `cargo binstall cargo-dylint dylint-link`).'
+        yellow '! cargo-dylint not found on PATH — skipping dylint check (install from source with `cargo install cargo-dylint dylint-link`).'
     fi
 else
     yellow '! cargo not found on PATH — skipping Rust format, doc, and dylint checks.'