# AI Assistant Guide for `google-cloud-swift`

This document outlines critical rules, coding standards, and workflow practices for contributing to this project. Please strictly adhere to these instructions.

## Code Style and Conventions

- **Google Swift Style**: This project follows the naming conventions and general practices defined in the [Google Swift Style Guide](https://google.github.io/swift/).
- **Swift Formatter**: Code formatting is verified and enforced via `swift-format`. **When the style guide and the formatter disagree, always prefer the output from `swift-format`.**

## Dependencies and Rust Core

## Code Generation (`generated/`)

- **Librarian Generated Code**: All contents inside the `generated/` directory are automatically generated by the `librarian` tool.
  - **NEVER manually edit the code in `generated/`**.
  - For maintenance instructions and regeneration commands, consult `doc/contributor/howto-guide-generated-code-maintenance.md`.

## Testing Strategy

- **Swift Testing Framework**: Always use `import Testing` for tests. Never use `import XCTest`.
- **Test Organization**: Group all the unit tests for a class or struct under a `@Suite struct` structure, named for the struct or class under test.
- **Targeted Testing**: Prefer testing packages individually instead of the entire monorepo tree to save build time. Use:
  ```bash
  swift test --package-path packages/${package_name}
  ```
- **Global Validation**: To perform full validation on all packages (formatting, linting, test coverage), examine the workflow scripts in the `ci/` directory (`ci/lint.sh`, `ci/test.sh`).
- **Integration Tests**: Integration tests require explicit Google Cloud credentials and are restricted behind traits. Use:
  ```bash
  env GOOGLE_CLOUD_PROJECT="<your-project>" swift test --traits IntegrationTests
  ```
