ss-cargo-deps-tidy

Files (2)

• SKILL.md
• Generate-Inventory.ps1 · scripts/

SKILL.md (first lines)

# ss-cargo-deps-tidy

Tidies Rust dependency declarations in Cargo.toml files to ensure uniform style, centralize version management and verify that minimum dependency version guarantees are upheld for published library crates.

Invoke this skill automatically after modifying Rust dependency declarations in Cargo.toml files. Batch changes or defer execution to pre-commit stage when possible to minimize the number of times this skill needs to be invoked.

# Prerequisites

This skill is ONLY for Rust/Cargo workspaces. It does not do anything for projects that do not use Rust and Cargo.

# Mission

This is a multi-stage workflow to ensure tidiness and logical correctness of dependency declarations in `Cargo.toml` files in a Rust workspace. Each stage fulfills a separate part of the mission:

- Unify style of dependency declarations to uphold high standards of consistency, maintainability and readability.
- Ensure that same-workspace dev-dependencies are always referenced by path only, enabling proper publishing order determination.
- Centralize version management of dependencies on the workspace level to avoid version inconsistencies and simplify maintenance.
- Disable use of default features for dependencies, ensuring that we always compile the minimum necessary feature set.
- Ensure that Cargo feature flags are specified on the package level, not on the workspace level, to avoid activating dependency features in needlessly large scope.
- Verify that minimum dependency version guarantees are upheld to prevent breaking changes for downstream users of published libraries.

# Scope

For optimal skill execution consistency, we always process every `Cargo.toml` file in the workspace as a single set. The set is determined by the workspace-level `Cargo.toml`'s `[workspace] members` and `[workspace] exclude` declarations, so any crates intentionally excluded by the user are skipped automatically.

Exception: if repo-specific agent guidelines exclude additional `Cargo.toml` files from processing, ignore them entirely unless they cause issues.
This may be relevant, for example, if some external crate is vendored in the repo and should be used as-is without modification.

# Workspace-level feature flags

While we typically want feature flags to be specified in `Cargo.toml` files of individual packages, there are some exceptions:

- `std` / `alloc` / `async` - these are almost always used when working against a fully featured Rust environment, so define
  these on the workspace level to avoid repetition. Exception: if the repo-level agent guidelines say that the repo is intended
  to support no-std or other limited environments, do not define these features on the workspace level. Alternative phrasings
  like `use_std` or `use_alloc` are also fine as it is the intent that matters.
- `clap/default` - `clap` is a commonly used package for CLI parsing and disabling its default feature flags tends to result in difficult to
  debug issues like "--help just does not work". As these issues are rarely discovered by automated tests, we explicitly re-enable the
  `default` feature for `clap` on the workspace level. It is just a special package because it "misuses" Cargo feature flags for things
  other than enabling parts of the API surface.
- `argh/default` - same rationale as `clap/default`, as it is another CLI parsing library.

# Verifying workspace build

When verifying that the workspace builds successfully, prefer repo-specific verification commands (if found in agent instructions,
justfiles or similar).

If no repo-specific verification commands are found, use all of the following for verification:

- `cargo check --workspace --all-targets`
- `cargo check --workspace --all-targets --release`
- `cargo check --workspace --all-targets --all-features`

We consider verification successful if all of the above commands complete without warnings or errors.

# Workflow

Execute all stages in sequence to complete the workflow.

# Stage 1: Create inventory of dependency declarations

**This stage is your FIRST action in the workflow.** Before opening, viewing, reading or listing any `Cargo.toml` file in the workspace, run the native inventory command described below. The inventory is the single source of truth for every later stage; reading manifests by hand is wasted work and burns through your turn budget before you have made any edits.

**Anti-pattern (do not do this):** opening the workspace, listing `packages/`, and then issuing one `view` call per `Cargo.toml`. The inventory captures every declaration in every manifest - name, section, version, features, default-features, path, style, line number, raw text - so you never need to read manifests up front. You only open a specific manifest later when a filter query has identified a concrete edit that needs to be made in it.

Generate the inventory once at the start of the workflow and write it to a temporary file. All subsequent stages run filter queries against the loaded object - they never load the raw file contents into the conversation.

**Critical:** Always invoke the native command with `--output-path`. The JSON body can easily exceed 100 KB on real workspaces and is not suitable for direct inclusion in the agent context window. Do not `Get-Content` the inventory file without an immediate `| ConvertFrom-Json` and a follow-up filter; do not paste, summarize, or quote its raw contents. Inventory `sameWorkspace` is a tidy name/path classification, not a claim about Cargo registry resolution.

```powershell
#Requires -Version 7.6

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
$PSNativeCommandUseErrorActionPreference = $true

$inventoryPath = Join-Path ([IO.Path]::GetTempPath()) "cargo-deps-inventory-$([guid]::NewGuid()).json"
$previousNativeErrorPreference = $PSNativeCommandUseErrorActionPreference
$PSNativeCommandUseErrorActionPreference = $false
try {
    & ss-ai cargo inventory `
        --workspace-manifest '{{WORKSPACE_MANIFEST}}' `
        --output-path $inventoryPath
} finally {
    $PSNativeCommandUseErrorActionPreference = $previousNativeErrorPreference
}
if ($LASTEXITCODE -ne 0) {
    throw 'Cargo inventory generation failed.'
}
Write-Host "Inventory written to: $inventoryPath"
```

| Placeholder | Description |
| --- | --- |
| `WORKSPACE_MANIFEST` | Absolute path to the workspace-level `Cargo.toml`. |

If the command fails, stop and report its diagnostic; do not proceed with a partial inventory. On success, use the printed output path for the following queries.

The command discovers all member packages automatically by expanding the workspace `members` / `exclude` declarations, so the workspace-level `Cargo.toml` is the only path you need to provide.

Record the printed path. Each subsequent stage may run in its own PowerShell session, so every stage that needs the inventory reloads it from this path before running its filter queries:

```powershell
$inv = Get-Content -LiteralPath '<inventory-path-from-stage-1>' -Raw | ConvertFrom-Json
```

Tip: when no edits are needed (i.e. you are only running filter queries, not iterating with edits in between), you can batch multiple stages into a single PowerShell session - load `$inv` once at the top of the script and run each stage's filter query against it. This avoids paying the PowerShell startup cost per stage.

## Inventory schema

`$inv` is a `PSCustomObject` with:

- `workspaceRoot` - absolute path to the workspace root directory.
- `workspaceManifest` - `{ path, package, isVirtualWorkspace }` describing the workspace-level `Cargo.toml`.
- `memberManifests` - array of `{ path, package }` for every member `Cargo.toml`, with workspace-relative paths.
- `scannedAt` - ISO timestamp of when the scan ran.
- `dependencies` - array of declaration records (see below). One record per declared dependency.

Each `$inv.dependencies` record:

From sandersaares/ss-ai, MIT.

More from sandersaares/ss-ai