pyopenapi-gen 0.8.3__tar.gz

pyopenapi_gen-0.8.3/.bandit

@@ -0,0 +1 @@
+skips: ['B101', 'B404', 'B603', 'B110', 'B108']

pyopenapi_gen-0.8.3/.cursor/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "nodejs-debugger": {
+      "command": "npx",
+      "args": [
+        "@hyperdrive-eng/mcp-nodejs-debugger"
+      ]
+    }
+  }
+}

pyopenapi_gen-0.8.3/.cursor/rules/architecture.mdc

@@ -0,0 +1,86 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Cursor Rule: architecture
+
+## Purpose
+This rule introduces the crucial classes and the overall architecture of the Python OpenAPI client generator. It is intended to provide a high-level mental model for developers and AI agents working on the codebase.
+
+---
+
+## Core Architectural Concepts
+
+### 1. **Intermediate Representation (IR)**
+- **IRSpec, IROperation, IRParameter, IRRequestBody, IRResponse, IRSchema**
+  - These dataclasses represent the parsed and normalized OpenAPI spec.
+  - All code generation is based on this IR, not the raw OpenAPI dict.
+
+### 1.5. **Parsing and Loading Architecture**
+- **Loader (core/loader/)**
+  - `loader.py` - Main loader orchestration
+  - `operations/` - Operation parsing (parser.py, post_processor.py, request_body.py)
+  - `parameters/` - Parameter parsing (parser.py)
+  - `responses/` - Response parsing (parser.py)
+  - `schemas/` - Schema extraction (extractor.py)
+- **Schema Parsing (core/parsing/)**
+  - `schema_parser.py` - Core schema parsing logic
+  - `unified_cycle_detection.py` - Comprehensive cycle detection system
+  - `context.py` - ParsingContext for state management
+  - `ref_resolution/` - Reference resolution helpers
+  - `keywords/` - Keyword-specific parsers (allOf, oneOf, etc.)
+  - `transformers/` - Schema transformation utilities
+
+### 2. **Visitors**
+- **Visitor (base class)**
+  - Generic base for all code generation visitors. Uses the visitor pattern to traverse IR nodes.
+- **EndpointVisitor**
+  - Renders Python code for endpoint client classes and methods from IROperation nodes.
+- **ModelVisitor**
+  - Renders Python dataclasses or enums from IRSchema nodes.
+- **ClientVisitor**
+  - Renders the main APIClient class, which aggregates tag clients and manages transport.
+- **ExceptionVisitor**
+  - Renders exception alias classes for HTTP error codes.
+- **DocsVisitor**
+  - Renders Markdown documentation from the IR.
+
+### 3. **Emitters**
+- **Emitters (e.g., EndpointsEmitter, ModelsEmitter, ClientEmitter, ExceptionsEmitter, DocsEmitter)**
+  - Orchestrate the code generation process for each major output (endpoints, models, client, exceptions, docs).
+  - Use the corresponding visitor to render code, then write files to disk.
+
+### 4. **Helpers and Utilities**
+- **CodeWriter**
+  - Utility for building Python code with correct indentation and formatting.
+- **NameSanitizer**
+  - Ensures all generated names are valid Python identifiers.
+- **RenderContext**
+  - Tracks imports, file paths, and other state during code generation.
+
+### 5. **Authentication and Transport**
+- **HttpTransport (protocol), HttpxTransport (default implementation)**
+  - Abstract and concrete classes for HTTP communication, supporting pluggable authentication.
+- **BaseAuth and plugins**
+  - Protocol and implementations for authentication schemes (Bearer, API key, OAuth2, etc.).
+
+---
+
+## Architectural Flow
+1. **Spec Loading**: The OpenAPI spec is loaded and validated by the loader module.
+2. **Schema Parsing**: Raw schema dictionaries are parsed into IR dataclasses using the parsing module, with unified cycle detection handling circular references.
+3. **IR Construction**: Complete IRSpec object is built with all operations, parameters, responses, and schemas.
+4. **Code Generation**: Emitters use visitors to traverse the IR and generate code for models, endpoints, client, exceptions, and docs.
+5. **Helpers**: Utilities like CodeWriter and NameSanitizer ensure code quality and correctness.
+6. **Output**: Generated code is written to disk as a ready-to-use Python package.
+
+---
+
+## Key Principles
+- **Single Responsibility**: Each class/module has a focused purpose.
+- **Extensibility**: New emitters, visitors, or plugins can be added without modifying core logic.
+- **Strong Typing**: All IR and generated code is strongly typed.
+- **Separation of Concerns**: Parsing, code generation, and file I/O are clearly separated.
+- **Unified Cycle Detection**: A single, comprehensive system handles all circular reference scenarios consistently.
+- **Modular Parsing**: Schema parsing is broken into focused, testable components.

pyopenapi_gen-0.8.3/.cursor/rules/coding-conventions.mdc

@@ -0,0 +1,190 @@
+---
+description: >-
+  Python Coding Conventions — enforce Design-by-Contract without
+  external libraries, ensure Separation of Concerns, Test-Driven
+  Development, high coverage & first-class documentation.
+globs: ["**/*.py"]
+alwaysApply: true
+---
+
+# Python Coding Conventions
+
+> **Purpose**  
+> Guarantee that every line of Python in this repository is **clear,
+> maintainable, testable and rigorously specified by contract & tests**.
+
+---
+
+## 1. Core Principles
+
+1. **Design by Contract (DbC)** — every public function/method *must*
+   declare and enforce **pre-conditions**, **post-conditions** &
+   **invariants**.
+2. **Separation of Concerns** — single responsibility per module, class
+   and function; avoid God classes & long functions.
+3. **Clarity & Readability** — code is read far more than written;
+   prefer explicitness over cleverness.
+4. **Maintainability & Extensibility** — design for change; prefer
+   composition to inheritance; follow SOLID (esp. SRP, OCP, LSP, DIP).
+5. **Test-Driven Development** — write the failing test first; tests are
+   executable specifications; aim for ≥ 90 % **branch** coverage.
+6. **Comprehensive Documentation** — docstrings & type hints are
+   mandatory; docs express the contract.
+
+---
+
+## 2. Design by Contract Without External Libraries
+
+### 2.1 Contract Enforcement
+
+* Use **plain `assert` statements** to guard pre-conditions at the top
+  of the function and post-conditions at the end. Use
+  `__post_init__` (dataclasses) or property setters to maintain
+  invariants.
+* Never disable contract `assert`s in production; they are part of
+  behaviour. Configure the runtime to **never run with `-O`/`PYTHONOPTIMIZE`**.
+* Assertions must be **side-effect-free** and cheap.
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Account:
+    total: int
+
+    def __post_init__(self) -> None:
+        # Class invariant
+        assert self.total >= 0, "total must be non-negative"
+
+    def deposit(self, amount: int) -> None:
+        """Deposit money.
+
+        Contracts:
+            Pre-conditions:
+                - ``amount`` > 0
+            Post-conditions:
+                - ``self.total`` increased by exactly ``amount``
+        """
+        # Pre-condition
+        assert amount > 0, "amount must be positive"
+
+        old_total = self.total
+        self.total += amount
+
+        # Post-condition
+        assert self.total == old_total + amount, "balance unchanged"
+```
+
+### 2.2 Contract Documentation
+
+Extend docstrings with a **Contracts** section using the following
+markers (Google style or reST is accepted):
+
+```
+Contracts:
+    Preconditions:
+        - <condition>
+    Postconditions:
+        - <condition>
+    Invariants:
+        - <condition>
+```
+
+Write conditions in **business vocabulary**, not implementation detail.
+
+### 2.3 Contract Testing
+
+* Unit tests **duplicate the contract** so failures show friendly
+  messages rather than bare AssertionErrors.
+* When a contract fails, the test should describe the violated
+  assumption in its name.
+
+---
+
+## 3. Separation of Concerns & Structure
+
+* **Modules**: logically cohesive; avoid mixed concerns.
+* **Functions**: ≤ 40 logical lines; prefer pure functions.
+* **Classes**: ≤ 400 logical lines & ≤ 7 public methods.
+* **Layers**: domain → application/service → infrastructure. Enforce via
+  package structure: `domain/*`, `services/*`, `infra/*`.
+* **Dependency Direction**: higher layers must not import lower layers.
+
+---
+
+## 4. Code Style & Readability
+
+| Aspect         | Rule                                                   |
+| -------------- | ------------------------------------------------------ |
+| **Formatting** | `black` (line length 120) + `ruff format`               |
+| **Linting**    | `ruff check` for linting and import sorting             |
+| **Typing**     | `mypy --strict` is CI-blocking                         |
+| **Naming**     | PEP 8: classes `PascalCase`, funcs `snake_case`        |
+| **Patterns**   | Prefer **dataclasses** & **enums** over raw tuples/str |
+| **Globals**    | No mutable module-level state                          |
+
+---
+
+## 5. Testing Conventions
+
+* Use **pytest** with `pytest-cov` & **hypothesis** for property tests.
+* Directory: mirror package structure under `tests/`.
+* Every bug fix requires a *regression test*.
+* **Coverage gate**: branches ≥ 90 % enforced by CI.
+* Tests are *specifications* — structure names as
+  **Given\_When\_Then**.
+* Keep tests **fast & deterministic** (< 200 ms each).
+
+```python
+def test_deposit_increases_balance():
+    # Given
+    acc = Account(total=0)
+    # When
+    acc.deposit(50)
+    # Then
+    assert acc.total == 50
+```
+
+---
+
+## 6. Documentation Standards
+
+* **Docstrings**: PEP 257; include **Contracts** block where relevant.
+* Use **reST** or **Google style**, but be consistent project-wide.
+* Provide runnable examples (`doctest`).
+* Generate API docs with **Sphinx + autodoc**; CI fails on warnings.
+
+---
+
+## 7. Tooling & Continuous Integration
+
+1. **Pre-commit hooks**: `black`, `isort`, `flake8`, `mypy`.
+2. **CI stages** (GitHub Actions):
+
+   1. *Static Analysis* – format, lint, type checks.
+   2. *Unit Tests* – `pytest -q --cov`.
+   3. *Docs* – `sphinx-build -n -W . ./_build`.
+3. **Fail-fast** – pipeline stops on first violation.
+
+---
+
+## 8. Prohibited / Discouraged Patterns
+
+* Catching broad `Exception` or using bare `except`.
+* Hidden side-effects or implicit I/O in domain logic.
+* Monolithic script files; always package code.
+* Circular imports — resolve with adapter modules.
+* Premature optimisation; measure before optimising.
+
+---
+
+## 9. AI / Agent Instructions
+
+* Generated code **should include asserts and Contracts docstrings** where appropriate.
+* When editing legacy code lacking contracts/tests, suggest refactor + tests as a separate task.
+* Prefer clear names & explicit types over brevity.
+* **Note**: The current codebase is transitioning to full Design by Contract compliance. Focus on critical business logic for contract enforcement.
+
+---
+
+### End of Rule

pyopenapi_gen-0.8.3/.cursor/rules/project-goal.mdc

@@ -0,0 +1,84 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# PROJECT GOAL
+
+The Python OpenAPI client generator must produce client code that:
+
+## 1. Direct API Communication
+- Communicates directly with the API as defined by the provided OpenAPI spec.
+- Accepts strongly typed input parameters (matching the OpenAPI schema).
+- Returns strongly typed responses (matching the OpenAPI schema).
+
+## 2. Authentication & Transport
+- Supports authentication and lazy loading.
+- Uses a system default HTTP implementation by default, but allows the user to inject a custom HTTP class for communication.
+
+## 3. Out-of-the-Box Functionality
+- The generated code is fully functional out of the box—no stubs, placeholders, or manual implementation required for basic API communication.
+
+## 4. IDE Support
+- The generated client must support code completion and type hints in IDEs (such as PyCharm, VSCode, etc.), leveraging Python's type annotations and docstrings for maximum developer productivity.
+
+## 5. Error Handling
+- All errors that the client receives from the API must be handled by raising an exception; only successful responses are returned as response types.
+
+---
+
+## 6. Client Independence & Core Module
+
+**The generated client code must be fully independent and must not require any runtime dependency on `pyopenapi_gen` itself.**
+
+- All runtime dependencies (e.g., base transport, authentication protocols, exceptions, utility classes) must be generated into a `core` module/folder within the output package.
+- The generator must provide an option to customize the name and location of this `core` folder, to support scenarios where multiple clients are generated for the same system and can share a single core implementation.
+- All imports in the generated client code must be relative (e.g., `from .core.http_transport import HttpTransport`) or from the standard library/allowed third-party packages.
+- No `from pyopenapi_gen...` imports should appear in the generated output.
+
+### Example Output Structure
+
+```
+my_generated_client/
+    core/
+        http_transport.py
+        auth.py
+        exceptions.py
+        ...
+    models/
+        ...
+    endpoints/
+        ...
+    __init__.py
+    py.typed
+    README.md
+```
+
+Or, with a shared core:
+
+```
+shared_core/
+    http_transport.py
+    auth.py
+    exceptions.py
+    ...
+client_a/
+    models/
+    endpoints/
+    ...
+client_b/
+    models/
+    endpoints/
+    ...
+```
+*(Clients can import from the shared core as configured.)*
+
+---
+
+## 7. Documentation
+- The generated client’s README must clearly state that it is independent and does not require `pyopenapi_gen` at runtime.
+- If the core module is shared, document how to set up the import path.
+
+---
+
+**This ensures that the generated client is robust, portable, and easy to integrate into any Python project without extra dependencies.**

pyopenapi_gen-0.8.3/.cursor/rules/testing.mdc

@@ -0,0 +1,185 @@
+---
+description: 
+globs: tests/**/*.py
+alwaysApply: false
+---
+1. 🎯 Purpose
+
+To ensure all tests — both unit and integration — are:
+
+- Precise in intent
+- Fully verifying the contract of the component under test
+- Isolated from unrelated dependencies
+- Described clearly for human readability and maintainability
+
+This cursor rule must be followed both by human developers and any AI writing tests.
+
+2. ✅ Scope of Tests
+
+2.1 Unit Tests
+
+Must test the smallest testable part of the application in isolation.
+
+- Only one unit (e.g., function, class method) should be tested per test case.
+- External dependencies (DBs, APIs, services, time, randomness, etc.) must be mocked or stubbed.
+
+2.2 Integration Tests
+
+Should test cooperation between units (e.g., service layer + repository).
+
+- Can include real implementations of multiple components, but external system boundaries must still be mocked unless explicitly testing integrations.
+- Only use real I/O for designated "integration" or "e2e" test environments, never in unit tests.
+
+3. 📋 Test Case Structure
+
+All tests must follow this standard format:
+
+```python
+def test_<unit_of_work>__<condition>__<expected_outcome>():
+    """
+    Scenario:
+        - Description of the test scenario in 2–4 lines of natural language.
+        - Describe what is being tested and why it's important.
+
+    Expected Outcome:
+        - Explicitly state what the correct result should be (including side effects).
+    """
+    # Arrange
+    # Setup necessary inputs and mocks
+
+    # Act
+    # Run the function or method being tested
+
+    # Assert
+    # Check for correct result and side effects
+```  
+
+4. 🧠 AI Agent Testing Rules
+
+When AI is tasked to write tests, it must:
+
+- Use the above structure.
+- Generate a clear, natural-language docstring summarizing the scenario and expected result.
+- Mock all dependencies not directly under test.
+- Avoid redundant assertions or low-value "happy path only" testing — focus on variation in input and edge cases.
+- Ensure high coverage of:
+  - Control flow (if/else, error branches)
+  - Contract fidelity (input/output invariants, exceptions)
+  - State changes (data updates, method calls)
+- Do not test third-party libraries (assume their correctness).
+
+5. 🔬 Coverage Requirements
+
+- All public methods and functions must be tested with 100% logical branch coverage.
+- Edge cases must be included (e.g. empty list, None, 0, large inputs).
+- For integration tests, ensure interface expectations between units are fully verified.
+- Use pytest-cov or equivalent to enforce and review coverage.
+
+6. 🔄 Isolation Rule
+
+- Only the unit or flow under test may contain logic.
+- Everything else (e.g., repositories, downstream APIs, services, clocks, logging, randomness) must be mocked using unittest.mock, pytest-mock, or equivalent.
+- Use fixtures where applicable, but avoid overly abstract or reused test setups that reduce test clarity.
+
+7. 🏷️ Naming & File Structure
+
+Test files mirror the code structure: foo.py → test_foo.py
+
+Use descriptive function names:
+
+- ✅ test_user_creation__invalid_email__raises_error
+- ❌ test_invalid_email
+
+8. 📚 Example
+
+```python
+def test_calculate_discount__vip_customer__applies_20_percent():
+    """
+    Scenario:
+        A VIP customer is eligible for a 20% discount. We want to verify that
+        the discount logic applies the correct rate based on the customer tier.
+
+    Expected Outcome:
+        The function should return the original price multiplied by 0.8.
+    """
+    # Arrange
+    price = 100.0
+    customer = Customer(tier="VIP")
+
+    # Act
+    result = calculate_discount(price, customer)
+
+    # Assert
+    assert result == 80.0
+```  
+
+9. 🧵 Integration Test Example
+
+```python
+def test_user_registration_flow__valid_data__creates_user_and_sends_email():
+    """
+    Scenario:
+        A new user registers with valid data. The service should create the user,
+        send a welcome email, and return a success status.
+
+    Expected Outcome:
+        - UserRepository.save is called with correct user
+        - EmailService.send_welcome_email is called
+        - Function returns success result
+    """
+    # Arrange
+    user_data = {"email": "test@example.com", "name": "Alice"}
+    repo = Mock()
+    email_service = Mock()
+    service = UserService(repo, email_service)
+
+    # Act
+    result = service.register_user(user_data)
+
+    # Assert
+    repo.save.assert_called_once()
+    email_service.send_welcome_email.assert_called_once()
+    assert result == {"status": "ok"}
+```
+## 10. Preferred Testing Framework & Style
+
+**10.1. Framework Choice:**
+    - All new Python unit tests and integration tests written for this project **MUST** use the `pytest` framework.
+    - Existing tests written using `unittest.TestCase` **SHOULD** be refactored to `pytest` style when those files are being significantly modified or as a dedicated refactoring effort to improve test suite consistency and leverage `pytest` features.
+
+**10.2. `pytest` Idiomatic Style:**
+    - **Assertions:** Tests **MUST** use plain `assert` statements for assertions (e.g., `assert result == expected`).
+    - **Fixtures:** Test setup, teardown, and dependency injection **MUST** be managed using `pytest` fixtures. Fixtures should be defined in the test file itself or in a relevant `conftest.py`.
+    - **Parameterization:** For testing multiple variations of inputs or conditions against the same test logic, `pytest.mark.parametrize` **MUST** be used to keep tests DRY (Don't Repeat Yourself) and data-driven.
+    - **Test Structure:** Test classes (if used) **SHOULD NOT** inherit from `unittest.TestCase`. They should be plain Python classes. Test functions can also be defined at the module level.
+    - **Exception Testing:** Testing for expected exceptions **MUST** use `pytest.raises` as a context manager (e.g., `with pytest.raises(SpecificException):`).
+
+## 11. Test Suite Analysis & Documentation
+
+**11.1. Purpose:**
+    - To maintain a continuous understanding of the test suite's health, coverage, and adherence to conventions.
+    - To provide a quick reference for the status and quality of tests within different modules.
+
+**11.2. Root Analysis Overview (`tests/test_analysis_overview.md`):**
+    - **Maintenance:** This document **MUST** be kept up-to-date.
+    - **Content:**
+        - It **MUST** list all test files and their current analysis status (e.g., "Analyzed", "Needs Analysis", "Analyzed - Empty").
+        - It **MUST** include links to per-directory detailed analysis documents.
+    - **Updates:** This document **SHOULD** be updated whenever:
+        - New test files are added.
+        - Existing test files are significantly refactored or moved.
+        - A new pass of test analysis is completed for any part of the suite.
+
+**11.3. Per-Directory Analysis Documents (e.g., `tests/<module>/<module>_analysis.md`):**
+    - **Maintenance:** These documents **SHOULD** be created or updated when a significant portion of tests within a directory/module is reviewed or refactored.
+    - **Content:** Each document **SHOULD** summarize:
+        - Overall conciseness and consistency of tests within that directory.
+        - Alignment with these testing conventions.
+        - Identification of any potentially contradictory expectations or areas for improvement specific to that module's tests.
+    - **Trigger for Updates:**
+        - After a focused review or refactoring effort on the tests within that directory.
+        - When the `test_analysis_overview.md` indicates a need for a detailed review of a specific area.
+
+**11.4. Responsibility for AI Agents:**
+    - When an AI agent is tasked with adding new test files or performing significant refactoring of existing tests, it **MUST** update the `tests/test_analysis_overview.md` to reflect the new or changed files and their status.
+    - If an AI agent performs an analysis pass on a directory as requested, it **MUST** contribute to or create the relevant per-directory analysis document.

pyopenapi_gen-0.8.3/.github/BRANCH_PROTECTION.md

@@ -0,0 +1,126 @@
+# Branch Protection Configuration
+
+This document outlines the required GitHub branch protection settings for the `develop` branch.
+
+## Required Settings
+
+### Branch Protection Rules for `develop`
+
+1. **Require pull request reviews before merging**
+   - Required approving reviews: 1
+   - Dismiss stale reviews when new commits are pushed: ✅
+   - Require review from code owners: ✅ (if CODEOWNERS file exists)
+
+2. **Require status checks to pass before merging**
+   - Require branches to be up to date before merging: ✅
+   - Required status checks:
+     - `quality-checks (3.10)`
+     - `quality-checks (3.11)` 
+     - `quality-checks (3.12)`
+     - `security-scan`
+     - `integration-tests`
+
+3. **Require conversation resolution before merging**: ✅
+
+4. **Require signed commits**: ❌ (optional)
+
+5. **Require linear history**: ❌ (optional)
+
+6. **Do not allow bypassing the above settings**: ✅
+
+7. **Restrict pushes that create files**: ❌
+
+8. **Allow force pushes**: ❌
+
+9. **Allow deletions**: ❌
+
+## How to Configure
+
+### Via GitHub Web Interface
+
+1. Go to your repository on GitHub
+2. Click on **Settings** → **Branches**
+3. Click **Add rule** or edit existing rule for `develop`
+4. Configure the settings as outlined above
+5. Save the branch protection rule
+
+### Via GitHub CLI (if available)
+
+```bash
+# Example command (adjust as needed)
+gh api repos/:owner/:repo/branches/develop/protection \
+  --method PUT \
+  --field required_status_checks='{"strict":true,"contexts":["quality-checks (3.10)","quality-checks (3.11)","quality-checks (3.12)","security-scan","integration-tests"]}' \
+  --field enforce_admins=true \
+  --field required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \
+  --field restrictions=null
+```
+
+## Quality Gates Enforced
+
+The pipeline enforces the following quality gates:
+
+### Code Quality
+- ✅ **Black formatting**: Code must be properly formatted
+- ✅ **Ruff linting**: No linting errors allowed
+- ✅ **MyPy type checking**: Strict type checking must pass
+
+### Testing
+- ✅ **Unit tests**: All tests must pass
+- ✅ **Integration tests**: End-to-end functionality verified
+- ✅ **Coverage**: Minimum 90% test coverage required
+- ✅ **Multi-Python version**: Tests on Python 3.10, 3.11, 3.12
+
+### Security
+- ✅ **Safety check**: No known vulnerabilities in dependencies
+- ✅ **Bandit scan**: Security linting for common issues
+
+### Functionality
+- ✅ **CLI functionality**: Command-line interface works correctly
+- ✅ **Client generation**: Generated clients have proper structure
+- ✅ **Package building**: Project can be built successfully
+
+## Workflow Files
+
+- `.github/workflows/pr-checks.yml`: Runs on PRs to develop branch
+- `.github/workflows/main-checks.yml`: Runs on pushes to main branch
+
+## Local Development
+
+Before creating a PR, run locally to ensure it will pass CI:
+
+```bash
+# Activate virtual environment
+source .venv/bin/activate
+
+# Auto-fix what's possible
+make quality-fix
+
+# Verify all quality gates pass (exactly matches CI pipeline)
+make quality
+
+# Run tests with coverage
+make test-cov
+```
+
+### Individual Commands (if needed)
+
+```bash
+# Quality checks (matches CI pipeline exactly)
+make format-check         # Black formatting check
+make lint                 # Ruff linting check  
+make typecheck            # mypy type checking
+make security             # Bandit security scanning
+
+# Testing
+make test                 # Run all tests
+make test-fast            # Stop on first failure (for debugging)
+
+# Auto-fixes
+make format               # Auto-format with Black
+make lint-fix             # Auto-fix linting with Ruff
+```
+
+### Why Use Make Commands?
+
+The `make` commands ensure you're running **exactly** the same checks as the CI pipeline. This prevents the "works locally but fails in CI" problem and provides fast feedback during development.