# Cosmos Pre Commit Validation

> Run pre-commit checks for a specific set of crates. Use this when validating changes under sdk/cosmos before committing or during code review.

- Skill: `azure-azure-sdk-for-rust/cosmos-pre-commit-validation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add azure-azure-sdk-for-rust/cosmos-pre-commit-validation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azure-azure-sdk-for-rust/cosmos-pre-commit-validation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Azure (https://skillmd.com/u/azure-azure-sdk-for-rust)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/azure-azure-sdk-for-rust/cosmos-pre-commit-validation

---

# Cosmos SDK Pre-Commit Checks

## When to use this skill

Use this skill when:

- Reviewing or validating changes in the Cosmos SDK
- Running pre-commit checks locally before pushing
- Performing focused code review on `sdk/cosmos/**`

## Behavior

Follow these steps strictly:

1. Determine the target path:
   - If the `scope` argument is specified and is not equal (case-insensitive) to `all` or `*`, set the target path to `sdk/cosmos/<scope>` (for example, if `scope` is `azure_data_cosmos`, use `sdk/cosmos/azure_data_cosmos` as the target path).
   - Otherwise, set the target path to `sdk/cosmos`.

2. Determine file scope:
   - If `changed-only` is `true` (the default), restrict scanning to `.rs` files that differ between the current local branch and `main`. Use `git diff --name-only main -- <target path>` (and include per-crate `tests/` directories) to obtain the list. Only `.rs` files in the result set are scanned; all other files are skipped.
   - If `changed-only` is `false`, scan **all** `.rs` files under the target path(s).
   - In both modes, **skip** files in `generated/` subdirectories — these are produced by external tools and must never be modified.

3. Validate using the Pre-Completion Validation Checklist in `sdk/cosmos/AGENTS.md`:
   - Formatting checks
   - Build succeeds for affected crates
   - Clippy lints pass for affected crates, with warnings treated as errors (`-D warnings`) to match CI behavior.
     Run clippy with `RUSTFLAGS=-D warnings` set:
     - Bash: `RUSTFLAGS='-D warnings' cargo clippy -p <crate> --all-features --all-targets`
     - PowerShell: `$env:RUSTFLAGS='-D warnings'; cargo clippy -p <crate> --all-features --all-targets; $env:RUSTFLAGS=$null`
   - **Re-run formatting** after any auto-fix: if `auto-fix` is true and clippy or other tools modified files,
     re-run `cargo fmt` to ensure the auto-fixed code is properly formatted (e.g., `cargo clippy --fix` can
     leave trailing blank lines when removing unused imports).
   - Documentation builds successfully where applicable
   - **Spell check (cspell)**: CI runs cspell on all changed files using the root config at `.vscode/cspell.json`;
     Cosmos-specific words are managed in `ignoreWords` in `sdk/cosmos/.cspell.json`. Run locally with:
     `npx cspell lint --config sdk/cosmos/.cspell.json --no-must-find-files <target path>/**`
     If `auto-fix` is true and unknown words are legitimate (e.g., API type names, technical terms),
     add them to `ignoreWords` in `sdk/cosmos/.cspell.json`.
   - Unit and emulator tests relevant to the touched modules and crates
   - **CI-gated tests**: Tests gated by `test_category` (e.g., emulator, multi-write) are always **compiled** but are **ignored at runtime** unless the corresponding cfg is set via `RUSTFLAGS`.
     This means `cargo check --tests` and `cargo test` will compile these tests without any special flags, so build errors are caught locally.
     `RUSTFLAGS` is only needed when you want to actually **run** the tests:
     - `RUSTFLAGS='--cfg test_category="emulator"' cargo test -p azure_data_cosmos --features fault_injection,key_auth --tests`
     - `RUSTFLAGS='--cfg test_category="multi_write"' cargo test -p azure_data_cosmos --features fault_injection,key_auth --tests`
     On Windows (PowerShell), set the env var first: `$env:RUSTFLAGS='--cfg test_category="emulator"'` then run the `cargo test` command, and clear it afterwards with `$env:RUSTFLAGS=$null`.
     These tests require a live Cosmos DB emulator or multi-region account to run.
     If `scope` targets a specific crate other than `azure_data_cosmos`, skip these checks.

4. Report results:
   - Summarize failures concisely
   - Include exact file paths and commands to reproduce
   - Do NOT auto-fix unless `auto-fix` argument is `true`

## Notes

- Never run repo-wide checks outside `sdk/cosmos`
- Avoid long-running integration tests unless explicitly requested