toko-tooling 0.37.1

Shared development tools, CI helpers and engineering rules for Dragginzgame
Documentation
# Git formatting hooks
<!-- Shared companions: rules/rust-workspaces.md -->

These rules are part of the [engineering baseline](../TOKO-TOOLING.md) for Rust
repositories. The standard pre-commit hook automatically formats the selected
commit payload. Repository-local Git hooks run before a commit; GitHub CI provides
the independent, non-mutating formatting gate.

## One formatting contract

- Vendor the reviewed Toko Tooling `.githooks/pre-commit` and
  `scripts/dev/install-git-hooks.sh`, with `scripts/ci/check-make-execution.sh`,
  unchanged in the [recorded snapshot]../docs/consuming-snapshots.md.
  Keep the hook and installer executable.
  Retire the superseded local formatter hook after reviewing its obligations.
- Every Rust repository provides `make fmt` and `make fmt-check`. Both cover the
  same maintained Rust workspaces, including standalone nested workspaces,
  examples or harnesses with their own manifests. Following IcyDB and Canic,
  `fmt` runs `cargo sort --workspace --grouped` before `cargo fmt` with explicit
  `--package` selections from that owner's Cargo `workspace_members`;
  `fmt-check` uses `cargo sort --workspace --grouped --check` and
  the same package selections with `-- --check`. Never use `cargo fmt --all`
  to traverse external sibling path dependencies. This sorts the root and every member's Cargo.toml,
  including members under `crates/`, `apps/` and approved layout trees, the root
  dependency catalog and inherited child tables. Explicitly cover
  standalone/excluded manifests outside that workspace's member set.
  Independent workspaces and their locations follow the
  [workspace layout rules]rust-workspaces.md; formatter coverage does not
  itself grant a layout exception.
- Use the `cargo-sort` tool for manifest ordering. Record an exact reviewed
  version in the consumer's developer and CI setup and use the same version in
  both; Toko Tooling's fixtures use `2.1.4`, matching Canic's reviewed selection.
  Install it during explicit setup, with `--version` and `--locked`, never during
  pre-commit or validation. Keep toolchain and rustfmt/tomlfmt configuration
  locally owned. Sorting preserves dependency identities, features, package
  versions, workspace inheritance, comments and selected lockfiles; it is not a
  dependency upgrade or release bump. See the
  [cargo-sort documentation]https://github.com/DevinR528/cargo-sort.
- Preserve local release groups first and the external dependency-role blocks with
  `cargo sort --workspace --grouped` for writing and add `--check` for checking.
  Apply the same selection to hooks, CI and selected-source release checks;
  the shared defaults already select grouped mode. Use the
  [dependency role labels]cargo-dependencies.md#dependency-roles-and-deployment-checks
  as section headers, with no repeated role annotation after each dependency.
  Sorting checks order; it does not verify dependency roles or registry
  publication.
- Additional formatting steps, such as derive sorting, may
  belong in those targets. They must have matching non-mutating checks, preserve
  dependency/version selections and work from tracked inputs in an isolated
  index snapshot. Formatting must not build, test, publish, clean artifacts,
  install tools or implicitly fetch dependencies. Keep network/cache preparation
  and frontend dependency setup outside the hook. A mixed Rust/frontend repo
  must supply an explicit local formatting adapter when its formatter requires
  untracked dependencies; do not patch the vendored hook or implicitly install
  those dependencies in a commit hook. Such an adapter runs explicitly prepared
  formatter executables against snapshot inputs, never against the original
  working tree.
- Include `fmt-check` in CI and the complete release gate. Prepared release
  metadata must also be consistently formatted before staging. A release must
  not rely on a commit hook to repair its saved staged payload; retain the
  release runner's exact commit-tree check.
- Keep routine formatting output concise and observable. Standard Rust passes
  show their type, workspace, progress and elapsed time; unchanged-input reuse
  must identify an identical successful selection, with prepared tools still
  admitted. Custom commands use the compact shared log wrapper. Failures produce
  a short failure line and a pointer to the retained log; preserve the command's
  failing exit status. Make may add its own error diagnostic. Do not hide
  failures, discard diffs or remove workspace/derive/frontend checks to reduce
  output. Retain failure logs in CI artifacts too.

Use the [consumer Make entrypoint](../docs/make-interface.md), which includes
the shared `make/rust-format.mk`:

```make
include make/consumer.mk
```

It supplies `format-tools-check`, `fmt` and `fmt-check`, using the shared
[formatter prerequisite check](../docs/verification-helpers.md#formatter-prerequisites)
and the `RUST_TOOL_VERSIONS` pin file (the reviewed snapshot catalog by default).
Formatting uses prepared tools offline and
disables automatic rustup installation. `FORMAT_CARGO` selects one executable
name or path, not a command string; export `RUSTUP_TOOLCHAIN` to select a compiler.
The include preserves the default goal and never activates hooks or installs
tools. Keep setup explicit and retain stronger consumer admission checks.
Its `run-rust-formatting.pl` companion owns standard Rust workspace orchestration,
input reuse, pass timings and retained logs. `run-formatting.sh` preserves compact
presentation for custom commands. Include the declared closure in snapshots and
isolated hook/adoption fixture inputs.
The adjacent `make/execution.mk` companion uses a recipe-scoped execution probe to
reject Make ignore-errors and non-executing modes before formatting recipes run. Select its
declared companion when exporting; a failing prerequisite alone cannot enforce
failure propagation under ignore-errors mode.
Admission checks both `MAKEFLAGS` and Make's retained `MFLAGS`, including when
`MAKEFLAGS` is cleared or replaced. Do not assign `MFLAGS` on the command line or
in a Makefile; the guard requires GNU Make's generated invocation flags.

Use the [declarative formatting inputs](../docs/make-interface.md#custom-formatting-without-replacement-recipes)
for independent workspaces, derive sorting and manifest order. Retire adapters
that only repeat that sequence after qualifying their actual callers. Keep local
adapters for additional policies such as frontend formatting; set both `FORMAT_WRITE_COMMAND` and
`FORMAT_CHECK_COMMAND` to their complete sequences before the include; add any
extra prerequisite checks to `format-tools-check`. Do not accidentally replace
existing coverage with the root-workspace defaults. Qualify the actual formatting
hook after adoption. The shared targets wrap each complete adapter once; a fixed
`bash -ec '...'` sequence works too. Do not create another workspace registry.
The wrapper accepts one command
and its literal arguments, runs it once, and preserves its exit status. Logs are
created beneath `RUNNER_TEMP`, otherwise `TMPDIR` or `/tmp`; only its own successful
temporary log is removed. The shared failure collector includes `formatting.*`.

When a recipe calls a tool available only through a Makefile-exported `PATH`,
use `env tool ...` (for example, `env cargo sort --workspace --grouped`) or an explicit
executable path. Apple's system Make can resolve a bare recipe command using
its original process PATH, even though the recipe receives the updated PATH.
Do not rely on an unrelated global installation to make the recipe work.

For a separate `testing/` workspace, also run `cargo sort --workspace --grouped testing`
before `cargo fmt --manifest-path testing/Cargo.toml --all`, with their `--check`
equivalents in `fmt-check`. Pass one workspace root per `cargo sort --workspace`
invocation. `cargo-sort` owns its ordering and TOML rendering; do not add a second
hand-written sort or rewrite dependency declarations to enforce ordering.

## Selected files and working edits

### Derive macros and dollar-prefixed paths

The selected `cargo-sort-derives` 0.14.1 uses literal replacements for `derive`
and `cfg_attr`, fixing the `$crate` corruption in 0.13.0 and 0.14.0. Its build
requires Rust 1.88 or newer; this is the formatter's compiler requirement, not a
change to a consumer library's MSRV. Consumer pins remain explicit inputs.

Toko Tooling's `test-frontend-formatting.sh` fixture sorts unprotected direct
and conditional macro derives through the real hook, compares the refreshed
staged bytes, compiles both exported macros from a separate crate and checks
ordinary sorting and repeat-run stability. Run that qualification on supported
native hosts; version probes alone do not establish semantic preservation.

Consumers adopting this pin explicitly prepare/check the new selected tools,
then qualify their own macros before removing corruption-workaround range
markers. Keep markers on consumers still using an affected formatter; retain
unrelated intentional sorting exclusions. This example must preserve both
literal `$crate` paths:

```bash
printf '%s\n' '#[derive($crate::exports::Debug, $crate::exports::Clone)]' |
  cargo sort-derives --stdin
```

The [upstream fix](https://github.com/lusingander/cargo-sort-derives/pull/28)
and [shared qualification](https://github.com/dragginzgame/toko-tooling/issues/113)
record the repair and remaining consumer/native acceptance. Do not infer
consumer adoption from the shared pin alone.

### Mixed Rust and frontend reference

Vendor `scripts/dev/format-frontend.sh` with the hook for a frontend using
Prettier's built-in parsers. Explicit setup prepares Node and dependencies with
the [npm pinning rules](dependency-pinning.md#frontend-and-npm-inputs). Before
committing, the caller exports `PRETTIER_BIN` as the absolute prepared executable
path (for example, `$PWD/frontend/node_modules/.bin/prettier`). An isolated index
export has no `node_modules`; never resolve that path relative to the export or
install packages inside it. The consumer's Makefile reads the version from the
selected tracked lockfile, for example:

```make
PRETTIER_VERSION = $(shell jq -er '.packages["node_modules/prettier"].version' frontend/package-lock.json)
FORMAT_WRITE_COMMAND = bash -ec 'perl scripts/ci/run-rust-formatting.pl --write; bash scripts/dev/format-frontend.sh --write frontend'
FORMAT_CHECK_COMMAND = bash -ec 'perl scripts/ci/run-rust-formatting.pl --check; bash scripts/dev/format-frontend.sh --check frontend'
include make/consumer.mk
fmt fmt-check: export PRETTIER_VERSION := $(PRETTIER_VERSION)
```

Retain the Rust prerequisite checks and all actual workspace roots described
above. The hook supplies `TOKO_TOOLING_FORMAT_FILES`, a NUL-delimited selection
outside the exported worktree. The helper formats matching selected frontend
paths inside that export; the hook alone refreshes the real index. Outside the
hook, `--write` and `--check` cover tracked frontend inputs, with `--check` always
checking the complete tracked scope. JavaScript/TypeScript, JSON, CSS/SCSS, HTML,
Markdown and YAML are selected; Prettier owns configuration and ignore behavior.
Generated files may be ignored only when the consumer's generation checks own
their correctness. Symlink inputs are refused. No Git staging or tool install
occurs in the helper, and formatter failures propagate.
Explicit checks/writes reject a missing scope directory, and a failed version
probe is rejected even if it prints the expected version. A hook selection with
no remaining frontend files is a valid no-op, including deletion of the last
frontend file; it does not require the prepared executable.

This is a reference for prepared executables and built-in parsers. A consumer
needing plugins or additional extensions owns their explicit prepared resolution
and focused adapter checks. Preserve config, version and lock selections from
the snapshot; do not make the formatter read unstaged configuration in the real
checkout. Qualify real Prettier on the declared native hosts before claiming
adoption; shared command-substitute tests prove wiring and selection only.
Toko Tooling additionally runs `scripts/ci/test-frontend-formatting.sh` with
locked real Prettier and Rust formatters in its native CI matrix. It exercises
selected-file refresh, snapshot configuration and ignore behavior, parse-failure
isolation, partial staging, and preservation of unrelated files and the npm lock.
Prepare its test-only dependencies with `npm ci --prefix ci/frontend`, using the
Node/npm selections in `ci/frontend/package.json`; validation never installs
them. A matching successful CI run qualifies this reference's built-in parsers,
not a consumer's plugins, configuration or adoption.
See the [Prettier CLI contract](https://prettier.io/docs/cli).

### Index ownership

- The hook records the selected added/modified/renamed files using NUL-delimited
  paths. It rejects a selected file with unstaged changes before formatting,
  including a partial selection of configuration or formatter inputs. Preserve
  the unstaged edits separately or finish staging that file, then retry.
- Formatting runs in a temporary export of the exact index, using its source,
  manifests, configuration and Make targets. It does not use unstaged working
  versions. It preserves executable lookup through the original checkout's
  prepared `.tools/host/bin` and `.tools/rust/common/bin`, in that order
  before the inherited PATH; an interactive shell export is not required for
  those common tools. Products requiring IC formatters explicitly publish their
  prepared IC PATH or select it in their Make recipes; index exports expose
  `TOKO_TOOLING_FORMAT_TOOLS_FROM` for the original checkout's tool root.
  Prerequisite checks still enforce the selected versions, and
  formatting never installs missing tools. It clears inherited Git
  repository/index variables for formatters,
  while preserving the original commit index for its own checks and staging.
  It rejects inherited Make ignore-errors, dry-run, question, touch and version-only modes
  before dispatch, so a skipped or failed formatter cannot refresh the index.
- Receipt checks using `install-rust-tools.sh --consumer "$(CURDIR)" --check`
  can inspect the original checkout's prepared Rust selections from the index
  export. The hook supplies `TOKO_TOOLING_FORMAT_WORKTREE` and
  `TOKO_TOOLING_FORMAT_TOOLS_FROM` as an internal, exact-worktree context.
  Catalog/lock selection and compiler resolution still use the export and its
  inherited declared environment. Mismatched or corrupt receipts refuse; setup
  in the export refuses. Keep stronger consumer prerequisites intact. An
  unrelated nested checkout cannot borrow these selections. This context grants
  no formatter permission to inspect or edit original source files.
- After successful formatting, the hook checks that the index and selected
  working files have not changed, copies formatting back to those selected files
  and refreshes only that selection. Unselected tracked files, untracked files
  and unrelated working edits remain untouched. Never use `git add -A`, add newly
  discovered formatting changes or stash/reset working edits inside the hook.
- If formatting fails, the real index and working files remain unchanged. A
  detected concurrent edit or staging change stops the hook; preserve that change
  and retry. Do not edit or stage concurrently with an active hook. If copying or
  staging itself fails, review the selected formatted files before retrying;
  no rollback may discard working edits.
- Snapshot formatting supports regular tracked files. Reject symlinks,
  submodules and unresolved index entries rather than following content outside
  the saved snapshot. A repository needing a different model requires an
  explicit maintainer-approved exception and an owned adapter outside the
  snapshot. Disposable formatter snapshots are helper-owned scratch, never a
  consumer build/evidence directory.

## Installation and adoption

The consumer Make entrypoint supplies `install-hooks` for Rust consumers through
`scripts/dev/install-git-hooks.sh --consumer <checkout>`. The destination is
required; neither invocation location nor installer location selects a checkout.
Keep the tracked hook
and its root-layout companions in the consumer, even when the installer itself
is in a nested snapshot. A focused include can still call that documented helper.

Run `make install-hooks` once per clone and call it from the documented developer
setup/update flow. It sets only repository-local `core.hooksPath=.githooks`.
The installer refuses to replace another effective hook path, including inherited
or deliberately disabled settings, or to disable an executable private hook in
the default Git hooks directory. Reconcile existing hook obligations explicitly
before changing their location. Setup never changes global Git configuration or
silently chmods tracked files.
Hook paths are compared literally, including trailing newlines. A failed Git
configuration read must stop setup rather than count as an absent setting.

Adding tracked hooks does not activate them in an existing clone. Verify the
effective `git config --get core.hooksPath`, executable mode, snapshot integrity,
formatter prerequisites and the consumer's actual `fmt`/`fmt-check` targets.
Exercise automatic refresh, partial-stage rejection, failed formatter isolation
and unrelated working-edit preservation on the declared Linux/macOS hosts.
Report source/snapshot adoption and local activation separately. Toko Tooling
distributes and tests the Rust hook; its own shell-only checkout does not activate
it.

Consumers may replace repeated mechanical adoption fixtures with
`scripts/ci/check-formatting-hooks.sh`, retaining their selected manifests,
formatter inputs and product-specific cases. Its [documented contract](../docs/verification-helpers.md#consumer-formatting-hook-adoption)
requires already-prepared tools and retains failed exports. A committed snapshot
and focused native consumer qualification are still required before deleting
superseded checks.

Hooks are developer convenience, not CI or release evidence. Git permits bypassing
pre-commit hooks; CI must still enforce formatting independently. See the official
[Git hook documentation](https://git-scm.com/docs/githooks) and
[rustfmt usage](https://github.com/rust-lang/rustfmt#running).