wry 0.5.0__tar.gz → 0.5.1.dev4__tar.gz

wry-0.5.1.dev4/.cursorrules

@@ -0,0 +1,193 @@
+# Cursor AI Rules for wry Repository
+
+> **Note**: These rules are the AI assistant's quick reference. For comprehensive guidelines,
+> examples, and detailed explanations, see `CONTRIBUTING.md`.
+
+## Pre-Commit Requirements
+
+Before making any commit, AI assistants MUST:
+
+1. **Update Documentation** (ALWAYS update CHANGELOG.md):
+   - **CHANGELOG.md**: ALWAYS add entry under [Unreleased] for ANY change
+   - README.md if user-facing changes
+   - AI_KNOWLEDGE_BASE.md if architecture/API changes
+   - Module docstrings if relevant
+
+2. **Ensure Code Quality**:
+   - Add type annotations to all new functions
+   - Add docstrings to all public functions/classes
+   - Follow DRY principles
+   - Remove dead code and unused imports
+
+3. **Update/Add Tests**:
+   - Add tests for new functionality
+   - Update tests for changed behavior
+   - Ensure tests pass (run pytest)
+
+4. **Run Checks**:
+   - Ensure pre-commit hooks will pass
+   - Fix linter errors (ruff, mypy)
+   - Format code properly (ruff format)
+
+5. **Follow Conventional Commits**:
+   - Use format: `type: description`
+   - Types: feat, fix, docs, refactor, test, chore, build
+
+## Reference
+
+**Full development guidelines**: See `CONTRIBUTING.md` for:
+
+- Complete code organization principles
+- Detailed examples of adding features
+- wry-specific development patterns
+- Comprehensive pre-commit checklist
+- Pull request process
+
+**Quick links**:
+
+- Architecture & concepts: `CONTRIBUTING.md` "Core Concepts" section
+- Code patterns: `CONTRIBUTING.md` "Configuration Models" section
+- Testing guide: `CONTRIBUTING.md` "Testing" section
+- Pre-commit checklist: `CONTRIBUTING.md` "Pre-Commit Checklist" section
+- Release workflow: `RELEASE_PROCESS.md` for creating releases
+
+## Enforcement
+
+The pre-commit hook automatically runs checks on commit.
+All checks must pass before commit succeeds.
+
+## General Development Guidelines
+
+### Date and Time
+
+- Use the `date` terminal command to learn the current date
+- Never assume or hardcode dates in dynamic contexts
+
+### Python Best Practices
+
+#### Type Annotations
+
+- **ALWAYS** add type annotations to all functions, methods, and class attributes
+- Include return types for all functions (use `-> None` for void functions)
+- Use proper generic types from `typing` module
+- Prefer modern Python 3.10+ syntax (e.g., `list[str]` over `List[str]`)
+
+#### Documentation
+
+- Add comprehensive docstrings to:
+  - All modules (at the top of the file)
+  - All classes (describing purpose, attributes, and usage)
+  - All public functions and methods (describing parameters, return values, and exceptions)
+- Use consistent docstring format (Google style preferred)
+
+#### Code Quality
+
+- **DRY Principles**: Don't Repeat Yourself - extract common logic into reusable functions/classes
+- **Clean Code**: Write self-documenting code with clear variable and function names
+- **No Dead Code**: Remove unused variables, functions, and commented-out code unless it serves as important documentation
+- **Maintainability**: Prioritize code that is easy to understand, modify, and extend
+
+### Linter and Type Checker Compliance
+
+#### Fixing Issues Properly
+
+- **ALWAYS** fix linter errors and type checker warnings properly
+- **AVOID** using ignore directives like `# type: ignore`, `# noqa` as quick fixes
+- **AVOID** using `cast()` unless absolutely critical for complex type scenarios
+- Investigate the root cause and fix issues with proper type annotations and code structure
+- If an ignore directive is truly necessary, add a detailed comment explaining why
+
+#### Working Directory
+
+- **ALWAYS** ensure you're in the correct directory before:
+  - Running commands
+  - Creating files
+  - Executing scripts
+  - Making git operations
+
+### Testing
+
+#### Test Coverage
+
+- **NEVER** ignore, skip, or disable test cases just to make test suites pass
+- If a test fails, fix the underlying issue or update the test if requirements changed
+- Add tests for all new functionality
+- Update tests when changing existing behavior
+- Ensure all tests **PASS** before considering work complete
+
+#### Test Organization
+
+- Place test code in the most logical location (follow project structure under `tests/`)
+- Name test files and functions clearly to indicate what they're testing
+- Use descriptive test names: `test_<function>_<scenario>_<expected_result>`
+
+### Documentation Management
+
+#### Markdown Files
+
+- **Do not create excessive markdown files** unless explicitly instructed
+- If markdown files exist, add content to the appropriate existing file
+- If unsure which file is appropriate, **ask the user** where content should go
+- Before creating a new markdown file, consider: Did the user actually request documentation?
+
+### Git Best Practices
+
+#### Committing Changes
+
+- Attempt to commit changes after completing major features or fixes
+- Use **Conventional Commits** format: `<type>: <description>`
+  - Examples: `feat: add comma-separated list support`, `fix: handle ClassVar in AutoWryModel`
+
+#### Pre-Commit Hooks - CRITICAL RULE
+
+- **NEVER** use `git commit --no-verify` or `--no-gpg-sign` to bypass pre-commit hooks
+- **ONLY EXCEPTION**: When the user explicitly says it's okay
+- If pre-commit hooks fail:
+  1. Fix the underlying issue (don't bypass)
+  2. Ask the user for guidance if you can't fix it
+  3. Wait for user approval before using --no-verify
+- Pre-commit hooks catch bugs, enforce quality, and save code review time
+- Bypassing them should be extremely rare (emergency situations only with approval)
+
+#### File Operations
+
+- **Strongly prefer** using Git commands for file operations:
+  - Use `git rm` instead of `rm` when deleting tracked files
+  - Use `git mv` instead of `mv` when moving/renaming tracked files
+- This ensures Git properly tracks file history instead of treating operations as delete+add
+- Always pass `--yes` or appropriate non-interactive flags to avoid user prompts
+- **NEVER** use `git push --force` to main/master without explicit user approval
+- **NEVER** use `git reset --hard` without explicit user approval
+
+## wry-Specific Guidelines
+
+### Model Development
+
+- All `WryModel` and `AutoWryModel` classes should use `ClassVar` for class-level configuration
+- Source tracking is a core feature - ensure it works for new features
+- List fields automatically get `multiple=True` unless `comma_separated_lists` is enabled
+- Document behavior in both README.md and AI_KNOWLEDGE_BASE.md
+
+### Click Integration
+
+- All Click parameter generation should respect Pydantic field metadata
+- Help text should be clear and include constraints
+- Arguments should inject help into docstrings (Click limitation workaround)
+
+### Testing Requirements
+
+- Test all four configuration sources: CLI, ENV, JSON, DEFAULT
+- Test source tracking for new features
+- Test both standard and edge cases
+- Use `CliRunner` for Click command tests
+
+## Summary
+
+These rules ensure:
+
+- High code quality and maintainability
+- Proper type safety and documentation
+- Comprehensive test coverage
+- Clean git history
+- Consistent development practices
+- wry's core features (source tracking, Click integration) work correctly

{wry-0.5.0 → wry-0.5.1.dev4}/AI_KNOWLEDGE_BASE.md

@@ -1,9 +1,16 @@
 # wry - Comprehensive AI/LLM Knowledge Base
 
-**Last Updated**: 2025-10-04
-**Version**: 0.3.2+
+**Last Updated**: 2025-10-14
+**Version**: 0.5.0+
 **Purpose**: Complete reference for AI assistants and LLMs to understand wry without reading the entire codebase
 
+**Related Documentation**:
+- 📖 **`CONTRIBUTING.md`** - Comprehensive contributor guide (referenced by `.cursorrules`)
+- 🤖 **`.cursorrules`** - AI assistant quick reference (references this file and CONTRIBUTING.md)
+- 📘 **`README.md`** - User-facing documentation
+- 📝 **`CHANGELOG.md`** - Version history and changes
+- 🚀 **`RELEASE_PROCESS.md`** - Release workflow (how to convert [Unreleased] → [X.Y.Z])
+
 ---
 
 ## Executive Summary
@@ -19,7 +26,9 @@
 
 **Key Innovation**: Single source of truth for configuration with comprehensive source tracking.
 
-**Stats**: 436 tests (all passing), 92%+ coverage, supports Python 3.10-3.12, Pydantic v2.11+ compatible
+**Stats**: 494 tests (all passing), 92%+ coverage, supports Python 3.10-3.12, Pydantic v2.11+ compatible
+
+**For Contributors**: See `CONTRIBUTING.md` for development guidelines and `.cursorrules` for AI assistant rules
 
 ---
 
@@ -2814,19 +2823,29 @@ Single source of truth: Pydantic model defines everything.
 - ✅ Multi-source configuration (CLI/ENV/JSON/DEFAULT)
 - ✅ Source tracking (know where every value came from)
 - ✅ Type safety (Pydantic + Click)
-- ✅ Comprehensive testing (407 tests, 92% coverage)
-- ✅ Excellent documentation (README + AI KB + examples)
+- ✅ Comprehensive testing (494 tests, 92% coverage)
+- ✅ Excellent documentation (README + AI KB + examples + CONTRIBUTING)
 
 **For AI assistants**:
 
-- Start with `examples/source_tracking_comprehensive.py` to understand the system
-- Reference this knowledge base for details
-- Check version for bug fixes (v0.2.2 critical)
+- **Follow** `.cursorrules` for quick development rules
+- **Reference** this knowledge base (AI_KNOWLEDGE_BASE.md) for technical details
+- **Check** `CONTRIBUTING.md` for complete development guidelines
+- Start with comprehensive examples to understand the system
+- Check version for bug fixes (v0.2.2 critical, v0.5.0 adds list support)
 - Point users to examples for patterns
 - Use `show_help_index()` to help users find documentation
 
+**For Contributors**:
+
+- **Read** `CONTRIBUTING.md` for complete guidelines
+- **Follow** `.cursorrules` if using Cursor AI
+- **Reference** this knowledge base for architecture details
+- **Check** `CHANGELOG.md` for version history
+- **See** `RELEASE_PROCESS.md` for creating releases
+
 ---
 
-**End of Knowledge Base** - Version 0.2.3+ - Last Updated: 2025-10-01
+**End of Knowledge Base** - Version 0.5.0+ - Last Updated: 2025-10-14
 
 **Access this**: `python -m wry.help_system ai` or `from wry import print_help; print_help('ai')`

{wry-0.5.0 → wry-0.5.1.dev4}/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Development guidelines** 📚
+  - Created `.cursorrules` as AI assistant's quick reference guide
+  - Created `CONTRIBUTING.md` as comprehensive contributor guide
+  - `.cursorrules` references `CONTRIBUTING.md` for detailed explanations
+  - Both tailored specifically for wry development patterns
+
+### Changed
+
+- **Documentation cross-references** 🔗
+  - README.md: Added Contributing section with links to CONTRIBUTING.md, .cursorrules, AI_KNOWLEDGE_BASE.md
+  - AI_KNOWLEDGE_BASE.md: Updated header with related documentation links
+  - AI_KNOWLEDGE_BASE.md: Updated version to 0.5.0+ and test count to 494
+  - AI_KNOWLEDGE_BASE.md: Added separate guidance sections for AI assistants and contributors
+  - Creates clear documentation hierarchy and navigation
+
+- **CHANGELOG requirements strengthened** ⚠️
+  - .cursorrules: Made CHANGELOG.md update mandatory and explicit (first item)
+  - CONTRIBUTING.md: Added prominent warning that CHANGELOG.md updates are required for every commit
+  - CONTRIBUTING.md: Listed all CHANGELOG sections (Added/Changed/Fixed/Deprecated/Removed/Security)
+  - RELEASE_PROCESS.md: Clarified [Unreleased] → versioned section workflow
+  - RELEASE_PROCESS.md: Documented that commits add to [Unreleased] during development
+  - RELEASE_PROCESS.md: Explained that release commit converts [Unreleased] to [X.Y.Z]
+
+### Tests
+
+- **Additional comma-separated test** (494 total tests)
+  - `test_model_wide_setting_does_not_affect_non_list_fields`
+  - Validates that `comma_separated_lists: ClassVar[bool] = True` only affects list fields
+  - Non-list fields (str, int, bool) work normally
+  - Explicit `click.option` decorators (like `-vvv` for verbose) are not affected
+  - Tests real-world use case: model-wide comma-separated + verbose counting
+
 ## [0.5.0] - 2025-10-14
 
 ### Added