# Tools

<!-- Generated by `npm run docs`. Do not edit by hand. -->

The extension registers **10 tools**. Adding an eleventh is a
deliberate decision: a new capability is expected to extend an existing tool
with a parameter unless it answers a question none of them can.

## `rust_build`

Preview or run cargo build. Classified as a mutating command, so execution needs execute=true and interactive confirmation.

- Label: Rust Build
- Prompt snippet: Preview or confirm a cargo build

Prompt guidelines:

- Use rust_build with execute=false first to review the exact cargo invocation.
- cargo build writes artifacts under target/; execute=true is required and the caller is asked to confirm.

Parameters:

```json
{
  "type": "object",
  "properties": {
    "targets": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Workspace members (-p)."
    },
    "allTargets": {
      "type": "boolean"
    },
    "features": {
      "anyOf": [
        {
          "type": "string",
          "const": "default"
        },
        {
          "type": "string",
          "const": "all"
        },
        {
          "type": "string",
          "const": "none"
        }
      ]
    },
    "workspace": {
      "type": "boolean"
    },
    "execute": {
      "type": "boolean"
    },
    "timeoutSeconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3600
    },
    "path": {
      "type": "string"
    }
  }
}
```

## `rust_check`

Run cargo check with --message-format=json and summarize structured compiler diagnostics without building final artifacts. Read-only for sources.

- Label: Rust Check
- Prompt snippet: Run cargo check and summarize compiler diagnostics

Prompt guidelines:

- Use rust_check to get structured compiler diagnostics by error code and first project frame.
- Diagnostics whose only frame is a registry or toolchain file are classified as library locations, not project causes.

Parameters:

```json
{
  "type": "object",
  "properties": {
    "targets": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "allTargets": {
      "type": "boolean"
    },
    "features": {
      "anyOf": [
        {
          "type": "string",
          "const": "default"
        },
        {
          "type": "string",
          "const": "all"
        },
        {
          "type": "string",
          "const": "none"
        }
      ]
    },
    "workspace": {
      "type": "boolean"
    },
    "execute": {
      "type": "boolean"
    },
    "timeoutSeconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1800
    },
    "path": {
      "type": "string"
    }
  }
}
```

## `rust_completion_evidence`

Build a conservative completion report from build and test execution results. Read-only.

- Label: Rust Completion Evidence
- Prompt snippet: Create evidence for a Rust completion report

Prompt guidelines:

- Use rust_completion_evidence before claiming Rust work is complete; a partial run is not evidence.

Parameters:

```json
{
  "type": "object",
  "required": [
    "preparationExecuted",
    "preparationOk",
    "testExecuted",
    "testOk",
    "stale",
    "changedPaths"
  ],
  "properties": {
    "preparationExecuted": {
      "type": "boolean",
      "description": "Whether cargo check / cargo build actually ran."
    },
    "preparationOk": {
      "type": "boolean"
    },
    "testExecuted": {
      "type": "boolean",
      "description": "Whether cargo test actually ran."
    },
    "testOk": {
      "type": "boolean"
    },
    "stale": {
      "type": "boolean",
      "description": "Whether a stale artifact was detected."
    },
    "changedPaths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 500
    }
  }
}
```

## `rust_environment`

Inspect the Rust toolchain that would actually run (rustc -vV, cargo, rustup state, rust-toolchain.toml channel) and the workspace target directory. Read-only.

- Label: Rust Environment
- Prompt snippet: Inspect the current Rust toolchain and workspace

Prompt guidelines:

- Use rust_environment before cargo diagnostics when the toolchain that would run is unknown.
- A rust-toolchain.toml naming an uninstalled channel makes rustup download it; rust_environment reports that before any build runs.

Parameters:

```json
{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Project directory or Cargo.toml path. Defaults to the cwd."
    }
  }
}
```

## `rust_failure_diagnose`

Classify the first actionable Rust error from structured cargo/rustc JSON output and point at the first project frame, excluding registry and toolchain frames. Read-only.

- Label: Rust Failure Diagnose
- Prompt snippet: Diagnose the first actionable Rust failure

Prompt guidelines:

- Use rust_failure_diagnose on bounded cargo/rustc output instead of reading a full compiler report in context.
- Frames inside ~/.cargo/registry or the rustup toolchain are library locations; the project frame is the cause.

Parameters:

```json
{
  "type": "object",
  "required": [
    "output"
  ],
  "properties": {
    "output": {
      "type": "string",
      "description": "Bounded stdout/stderr from a failing cargo command."
    },
    "path": {
      "type": "string",
      "description": "Project directory used to classify project versus library frames."
    }
  }
}
```

## `rust_project_inspect`

Read the cargo workspace model (members, default-members, editions, MSRV, targets, applied features) via cargo metadata --offline, and report consistency problems. Read-only.

- Label: Rust Project Inspect
- Prompt snippet: Inspect a Rust workspace manifest and its members

Prompt guidelines:

- Use rust_project_inspect before editing Cargo.toml or when the workspace membership or MSRV is unclear.
- default-members only covers part of the workspace; rust_project_inspect lists which members a bare cargo command would miss.

Parameters:

```json
{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Project directory or Cargo.toml path. Defaults to the cwd."
    },
    "scanUnusedDependencies": {
      "type": "boolean",
      "description": "Scan member .rs sources for declared dependencies that are never referenced. Informational: macro-only usage can look unused. Defaults to false."
    }
  }
}
```

## `rust_tdd_checkpoint`

Check whether production Rust changes have a related test change before implementation is considered complete. Read-only.

- Label: Rust TDD Checkpoint
- Prompt snippet: Check the Rust TDD checkpoint for changed files

Prompt guidelines:

- Use rust_tdd_checkpoint before reporting Rust implementation work as complete.

Parameters:

```json
{
  "type": "object",
  "properties": {
    "changedPaths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 500
    },
    "testChangedPaths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 500
    },
    "path": {
      "type": "string"
    }
  }
}
```

## `rust_test`

Preview or run cargo test and report what actually ran: ranTargets, tested packages, doc-test inclusion, zero-test runs, and failures. Read-only for sources; it compiles into target/.

- Label: Rust Test
- Prompt snippet: Preview or run cargo tests and report the execution scope

Prompt guidelines:

- Use rust_test with execute=false first; a preview is never a passing test run.
- A root cargo test only covers default-members; rust_test reports which members ran and which were skipped.
- A test run that executed zero tests is reported as not proven, not as a pass.

Parameters:

```json
{
  "type": "object",
  "properties": {
    "targets": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Workspace members to test (-p <crate>). Defaults to the whole workspace."
    },
    "allTargets": {
      "type": "boolean",
      "description": "Test benches and examples too (--all-targets)."
    },
    "docTests": {
      "type": "boolean",
      "description": "Include documentation tests. cargo test already does; set false to skip them (--tests)."
    },
    "features": {
      "anyOf": [
        {
          "type": "string",
          "const": "default"
        },
        {
          "type": "string",
          "const": "all"
        },
        {
          "type": "string",
          "const": "none"
        }
      ],
      "description": "Feature selection: --all-features or --no-default-features."
    },
    "workspace": {
      "type": "boolean",
      "description": "Cover every workspace member (--workspace). Defaults to true; false reproduces a bare cargo test, which only covers default-members."
    },
    "extraArgs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Extra cargo test arguments, passed verbatim."
    },
    "execute": {
      "type": "boolean"
    },
    "timeoutSeconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3600
    },
    "path": {
      "type": "string"
    }
  }
}
```

## `rust_test_select`

Map changed files to workspace crates through cargo metadata and select the crates to retest, including reverse dependencies. Read-only.

- Label: Rust Test Select
- Prompt snippet: Select focused Rust crates to test from changed files

Prompt guidelines:

- Use rust_test_select after changing Rust source to narrow cargo test to the affected crates instead of the whole workspace.
- Rust has no per-file test targets; the selection is a set of crates, so a "narrowed" run is reported in crates, not files.
- Set checkAllFeatures=true when a change may only compile under the default feature set; it verifies the affected crates with --all-features.

Parameters:

```json
{
  "type": "object",
  "properties": {
    "changedPaths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 500
    },
    "testFiles": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 1000
    },
    "features": {
      "anyOf": [
        {
          "type": "string",
          "const": "default"
        },
        {
          "type": "string",
          "const": "all"
        },
        {
          "type": "string",
          "const": "none"
        }
      ]
    },
    "checkAllFeatures": {
      "type": "boolean",
      "description": "Compile the affected crates with --all-features and report a feature-gated compilation gap. Defaults to false."
    },
    "timeoutSeconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1800
    },
    "path": {
      "type": "string"
    }
  }
}
```

## `rust_validation_bundle`

Preview or run one evidence-oriented sequence: cargo metadata --locked, cargo check, cargo test, execution-scope verification, and declared quality gates. Execution is opt-in.

- Label: Rust Validation Bundle
- Prompt snippet: Run the Rust build and test validation bundle

Prompt guidelines:

- Use rust_validation_bundle with execute=false first; a preview is never a passing validation.
- The bundle rebuilds before testing and treats a workspace member that produced no test binary, or a zero-test run, as a failed gate rather than a pass.

Parameters:

```json
{
  "type": "object",
  "properties": {
    "targets": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "features": {
      "anyOf": [
        {
          "type": "string",
          "const": "default"
        },
        {
          "type": "string",
          "const": "all"
        },
        {
          "type": "string",
          "const": "none"
        }
      ]
    },
    "quality": {
      "type": "boolean",
      "description": "Run declared quality gates (cargo clippy when configured, cargo fmt --check when rustfmt.toml exists). Defaults to true."
    },
    "execute": {
      "type": "boolean"
    },
    "timeoutSeconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3600
    },
    "path": {
      "type": "string"
    }
  }
}
```