flake8-elegant-objects 1.0.0__tar.gz → 1.1.0__tar.gz

flake8_elegant_objects-1.1.0/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ruff check:*)"
+    ],
+    "deny": []
+  }
+}

flake8_elegant_objects-1.1.0/CHANGELOG.md

@@ -0,0 +1,184 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2024-06-28
+
+### 🚀 Major Enhancements
+
+#### Enhanced Mutable Objects Detection
+
+- **Expanded EO008**: Complete rewrite from single checker to comprehensive modular package
+- **12 New Error Codes**: Added EO015-EO027 for granular mutability detection
+  - `EO015`: Mutable class attribute violations
+  - `EO016`: Mutable instance attribute violations
+  - `EO017`: Instance attribute mutation violations
+  - `EO018`: Augmented assignment mutation violations
+  - `EO019`: Mutating method call violations
+  - `EO020`: Subscript assignment mutation violations
+  - `EO021`: Chained mutation violations
+  - `EO022`: Missing factory methods violations
+  - `EO023`: Mutable default argument violations
+  - `EO024`: Missing immutability enforcement violations
+  - `EO025`: Copy-on-write violations
+  - `EO026`: Aliasing violations (exposing mutable state)
+  - `EO027`: Defensive copy violations
+
+#### Modular Architecture
+
+- **6 Specialized Checkers**: Organized mutable objects detection into focused modules
+  - `core.py`: Main orchestrator coordinating all sub-checkers
+  - `contract_checker.py`: Immutability contract enforcement
+  - `copy_on_write_checker.py`: Copy-on-write pattern validation
+  - `deep_checker.py`: Cross-class mutation analysis
+  - `factory_checker.py`: Factory method pattern validation
+  - `pattern_detectors.py`: Aliasing and defensive copy detection
+  - `shared_state_checker.py`: Shared mutable state detection
+
+### 🔧 Code Quality & Complexity Rules
+
+#### Ruff Integration
+
+- **McCabe Complexity**: Added `C90` with max-complexity = 10
+- **Nested Blocks**: Added `PLR1702` with max-nested-blocks = 5
+- **Set Literals**: Added `PLR6201` enforcement (tuple → set membership tests)
+- **Preview Mode**: Enabled ruff preview for latest pylint rules
+
+#### Code Refactoring
+
+- **Reduced Complexity**: Refactored methods from 6-7 nesting levels to ≤5
+- **Extract Methods**: Improved maintainability through helper method extraction
+- **Static Methods**: Added `@staticmethod` decorators where appropriate
+- **Type Safety**: Enhanced mypy compliance with proper type narrowing
+
+### 📈 Testing & Coverage
+
+#### Coverage Improvements
+
+- **90% Coverage**: Increased from 86% to 90% (+5% improvement)
+- **Pattern Detectors**: From 0% to 99% coverage
+- **New Test Cases**: Added 4 comprehensive test cases for EO026/EO027
+- **Integration Tests**: Enhanced end-to-end testing for new checkers
+
+#### Test Quality
+
+- **100 Tests**: All tests pass with enhanced coverage
+- **False Positive Prevention**: Added tests ensuring clean code doesn't trigger violations
+- **Real-world Scenarios**: Added aliasing and defensive copy test cases
+
+### 🏗️ Architecture Improvements
+
+#### Type Safety
+
+- **MyPy Clean**: Fixed all type errors with proper AsyncFunctionDef support
+- **Type Assertions**: Added strategic type narrowing for complex AST patterns
+- **Null Safety**: Enhanced null checking for optional attributes
+
+#### Documentation
+
+- **Updated README**: Comprehensive error code documentation with examples
+- **Project Structure**: Updated to reflect new modular architecture
+- **Coverage Badge**: Updated to reflect improved test coverage (90%)
+
+### 🐛 Bug Fixes
+
+- **Pattern Detector Integration**: Fixed unused pattern detectors (0% → 99% coverage)
+- **Type Compatibility**: Resolved mypy errors with union types
+- **Whitespace Handling**: Consistent code formatting across all files
+
+### ⚠️ Breaking Changes
+
+- **Mutable Objects**: EO008 now focuses specifically on dataclass violations
+- **New Error Codes**: Code that was previously missed may now trigger EO015-EO027
+
+### 🔄 Internal Changes
+
+- **Ruff Configuration**: Added comprehensive linting rules with complexity enforcement
+- **Parent Tracking**: Enhanced AST analysis with parent node mapping
+- **Modular Imports**: Reorganized imports for better dependency management
+
+---
+
+## [1.0.0] - 2024-06-21
+
+### 🎉 Initial Release
+
+This is the first release of `flake8-elegant-objects`, a comprehensive Flake8 plugin that enforces the core principles of Elegant Objects programming philosophy by Yegor Bugayenko.
+
+### ✨ Features
+
+#### Error Codes Implemented
+
+- **EO001-EO004**: No "-er" naming principle violations
+
+  - `EO001`: Class names ending in "-er" (Manager, Controller, Handler, etc.)
+  - `EO002`: Method names ending in "-er" (process → processing)
+  - `EO003`: Variable names ending in "-er" (parser → arguments)
+  - `EO004`: Function names ending in "-er" (analyzer → analysis)
+
+- **EO005**: No null (None) usage - prevents defensive programming and unclear contracts
+
+- **EO006**: No code in constructors - constructors should only assemble objects, not execute logic
+
+- **EO007**: No getters/setters - prevents data container anti-pattern, promotes behavioral objects
+
+- **EO008**: No mutable objects - enforces immutability for thread-safety and predictability
+
+- **EO009**: No static methods - promotes proper object-oriented design over procedural programming
+
+- **EO010**: No type discrimination - prevents isinstance/type casting that violates polymorphism
+
+- **EO011**: No public methods without contracts - requires Protocol/ABC contracts for public methods
+
+- **EO012**: Test methods should only contain assertThat statements - enforces focused, single-assertion tests
+
+- **EO013**: No ORM/ActiveRecord patterns - prevents mixing persistence with business logic
+
+- **EO014**: No implementation inheritance - promotes composition over inheritance
+
+#### 🔧 Technical Details
+
+##### Requirements
+
+- Python 3.10+
+- AST-based analysis for accurate code inspection
+- Zero runtime dependencies beyond Python standard library
+
+##### Code Quality
+
+- **86% Test Coverage**: Comprehensive test suite with real-world examples
+- **Type Safety**: Full mypy type checking compliance
+- **Code Style**: Ruff formatting and linting
+- **Documentation**: Extensive examples and principle explanations
+
+##### Performance
+
+- **Efficient AST Traversal**: Optimized single-pass analysis
+- **Minimal Memory Usage**: Lightweight violation tracking
+- **Fast Execution**: Suitable for large codebases
+
+#### 🧪 Testing
+
+- **14 Test Modules**: One dedicated test file per principle
+- **Real-world Examples**: Test cases based on actual code patterns
+- **Integration Tests**: End-to-end plugin functionality verification
+- **Continuous Testing**: Automated test execution with coverage reporting
+
+#### 🚀 Usage Examples
+
+```bash
+# Install
+pip install flake8-elegant-objects
+
+# Use as flake8 plugin
+flake8 --select=EO your_code/
+
+# Run standalone
+python -m flake8_elegant_objects your_code/
+
+# Configuration
+echo "[flake8]\nselect = E,W,F,EO" > .flake8
+```

flake8_elegant_objects-1.1.0/CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+## Development Commands
+
+```bash
+# Testing
+python -m pytest tests/ -v
+
+# Code Quality  
+mypy flake8_elegant_objects/
+ruff check flake8_elegant_objects/
+ruff format flake8_elegant_objects/
+
+# Plugin Usage
+python -m flake8_elegant_objects --show-source path/to/files/*.py
+flake8 --select=EO path/to/files/
+```
+
+## Architecture
+
+Flake8 plugin enforcing Elegant Objects principles (27 error codes EO001-EO027).
+
+**Core Components:**
+- `__init__.py`: ElegantObjectsPlugin orchestrating analysis
+- `base.py`: Principles base class, Violations type, ErrorCodes (EO001-EO027)
+- `no_er_name.py`: NoErName (EO001-EO004) 
+- `no_mutable_objects.py`: NoMutableObjects (EO008, EO015-EO027)
+- Other principle checkers: (EO005-EO007, EO009-EO014)
+
+**Pattern:** Plugin uses Principles which provides Violations (no None)
+
+## Error Codes
+
+### Naming Violations (EO001-EO004)
+- **EO001**: Class name violates -er principle
+- **EO002**: Method name violates -er principle
+- **EO003**: Variable name violates -er principle
+- **EO004**: Function name violates -er principle
+
+### Object Behavior (EO005-EO007)
+- **EO005**: Null (None) usage
+- **EO006**: Code in constructor
+- **EO007**: Getter/setter methods
+
+### Mutable Object Violations (EO008, EO015-EO027)
+- **EO008**: Mutable dataclass violation
+- **EO015**: Mutable class attribute violation
+- **EO016**: Mutable instance attribute violation
+- **EO017**: Instance attribute mutation violation
+- **EO018**: Augmented assignment mutation violation
+- **EO019**: Mutating method call violation
+- **EO020**: Subscript assignment mutation violation
+- **EO021**: Chained mutation violation
+- **EO022**: Missing factory methods violation
+- **EO023**: Mutable default argument violation
+- **EO024**: Missing immutability enforcement violation
+- **EO025**: Copy-on-write violation
+- **EO026**: Aliasing violation (exposing mutable state)
+- **EO027**: Defensive copy violation
+
+### Design and Architecture (EO009-EO014)
+- **EO009**: Static methods
+- **EO010**: isinstance/type casting
+- **EO011**: Public methods without contracts
+- **EO012**: Test methods with non-assertThat statements
+- **EO013**: ORM/ActiveRecord patterns
+- **EO014**: Implementation inheritance
+
+## Elegant Objects Principles
+
+**MUST follow:**
+- No null (None) - use empty lists instead
+- No code in constructors  
+- No getters/setters
+- No mutable objects
+- NO "-ER" NAMES: Manager, Controller, Helper, Handler, Parser, etc
+- No static methods
+- No instanceof/type casting  
+- No public methods without contracts
+- No statements in test methods except assertThat
+- No ORM/ActiveRecord
+- No implementation inheritance
+
+**Philosophy:**
+- Objects are living partners, not data containers
+- Declarative over imperative (`new Sorted(apples)` not `new Sorter().sort(apples)`)
+- Fail fast with exceptions, not null checks
+- Composition over inheritance
+- Immutability implied by design, not keywords
+
+## Code Style
+
+- No useless comments
+- Types: `Violations = list[Violation]`
+- Return empty lists `[]` instead of `None`
+- Extend lists instead of checking for None

{flake8_elegant_objects-1.0.0 → flake8_elegant_objects-1.1.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: flake8-elegant-objects
-Version: 1.0.0
+Version: 1.1.0
 Summary: Flake8 plugin enforcing Elegant Objects principles: no -er naming, no null, no getters/setters, immutable objects
 Project-URL: Homepage, https://github.com/AntonProkopyev/flake8-elegant-objects
 Project-URL: Repository, https://github.com/AntonProkopyev/flake8-elegant-objects.git
 Project-URL: Issues, https://github.com/AntonProkopyev/flake8-elegant-objects/issues
 Project-URL: Documentation, https://github.com/AntonProkopyev/flake8-elegant-objects#readme
-Author: Flake8 Elegant Objects Contributors
+Author: Anton Prokopyev
 License: MIT
 License-File: LICENSE
 Keywords: code-quality,elegant-objects,flake8,linting,object-oriented,python,static-analysis
@@ -31,25 +31,45 @@ Description-Content-Type: text/markdown
 # Flake8 ElegantObjects Plugin
 
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/AntonProkopyev/flake8-elegant-objects)
-[![Coverage](https://img.shields.io/badge/coverage-86%25-brightgreen.svg)](https://github.com/AntonProkopyev/flake8-elegant-objects)
+[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)](https://github.com/AntonProkopyev/flake8-elegant-objects)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Type checked: mypy](https://img.shields.io/badge/type_checked-mypy-blue.svg)](https://mypy.readthedocs.io/)
 [![Flake8](https://img.shields.io/badge/flake8-plugin-orange.svg)](https://flake8.pycqa.org/)
 
-Detects violations of core Elegant Objects principles including the "-er" naming principle, null usage, mutable objects, code in constructors, and getter/setter patterns.
+Detects violations of [Elegant Objects principles](https://www.elegantobjects.org/) including the "-er" naming principle, null usage, mutable objects, code in constructors, and getter/setter patterns.
 
 ## Error Codes
 
+### Naming Violations (EO001-EO004)
 - `EO001`: Class name violates -er principle
 - `EO002`: Method name violates -er principle
 - `EO003`: Variable name violates -er principle
 - `EO004`: Function name violates -er principle
+
+### Object Behavior (EO005-EO007)
 - `EO005`: Null (None) usage violates EO principle
 - `EO006`: Code in constructor violates EO principle
 - `EO007`: Getter/setter method violates EO principle
-- `EO008`: Mutable object violation
+
+### Mutable Object Violations (EO008, EO015-EO027)
+- `EO008`: Mutable dataclass violation
+- `EO015`: Mutable class attribute violation
+- `EO016`: Mutable instance attribute violation
+- `EO017`: Instance attribute mutation violation
+- `EO018`: Augmented assignment mutation violation
+- `EO019`: Mutating method call violation
+- `EO020`: Subscript assignment mutation violation
+- `EO021`: Chained mutation violation
+- `EO022`: Missing factory methods violation
+- `EO023`: Mutable default argument violation
+- `EO024`: Missing immutability enforcement violation
+- `EO025`: Copy-on-write violation
+- `EO026`: Aliasing violation (exposing mutable state)
+- `EO027`: Defensive copy violation
+
+### Design and Architecture (EO009-EO014)
 - `EO009`: Static method violates EO principle (no static methods allowed)
 - `EO010`: isinstance/type casting violates EO principle (avoid type discrimination)
 - `EO011`: Public method without contract (Protocol/ABC) violates EO principle
@@ -82,7 +102,7 @@ The plugin is automatically registered when the package is installed.
 
 ## Philosophy
 
-Based on Yegor Bugayenko's Elegant Objects principles, this plugin enforces object-oriented design that treats objects as living, thinking entities rather than data containers or procedure executors.
+Based on [Yegor Bugayenko](https://www.yegor256.com/)'s [Elegant Objects principles](https://www.elegantobjects.org/), this plugin enforces object-oriented design that treats objects as living, thinking entities rather than data containers or procedure executors.
 
 ### 1. No "-er" Entities (EO001-EO004)
 
@@ -113,12 +133,26 @@ Based on Yegor Bugayenko's Elegant Objects principles, this plugin enforces obje
 - ❌ `def get_value()` / `def set_value()` → ✅ Objects should expose behavior, not data
 - ❌ `user.getName()` → ✅ `user.introduce_yourself()` or `user.greet(visitor)`
 
-### 5. No Mutable Objects (EO008)
+### 5. No Mutable Objects (EO008, EO015-EO027)
+
+**Why?** Mutable objects introduce temporal coupling and make reasoning about code difficult. Immutable objects are thread-safe, predictable, and easier to test. This plugin provides comprehensive detection of various mutability patterns.
+
+**Basic Mutability Issues:**
+- ❌ `@dataclass class Data` → ✅ `@dataclass(frozen=True) class Data` *(EO008)*
+- ❌ `items = []` (class attribute) → ✅ `items: tuple = ()` *(EO015)*
+- ❌ `self.data = []` (instance attribute) → ✅ `self.data: tuple = ()` *(EO016)*
 
-**Why?** Mutable objects introduce temporal coupling and make reasoning about code difficult. Immutable objects are thread-safe, predictable, and easier to test.
+**Mutation Patterns:**
+- ❌ `self.items.append(x)` → ✅ `self.items = (*self.items, x)` *(EO019)*
+- ❌ `self.count += 1` → ✅ `return Counter(self.count + 1)` *(EO018)*
+- ❌ `self.data[key] = value` → ✅ Use immutable data structures *(EO020)*
+- ❌ `self.data = new_value` (after init) → ✅ Return new instance *(EO017)*
 
-- ❌ `@dataclass class Data` → ✅ `@dataclass(frozen=True) class Data`
-- ❌ `items = []` → ✅ `items: tuple = ()`
+**Advanced Patterns:**
+- ❌ `def items=[]:` (mutable defaults) → ✅ `def items=None:` + null object *(EO023)*
+- ❌ `return self._items` (exposing mutable state) → ✅ `return tuple(self._items)` *(EO026)*
+- ❌ `self.items = items` (no defensive copy) → ✅ `self.items = tuple(items)` *(EO027)*
+- ❌ Class with mutable state but no factory methods → ✅ Provide immutable factory methods *(EO022)*
 
 ### 6. No Static Methods (EO009)
 
@@ -200,17 +234,27 @@ ruff format flake8_elegant_objects/
 
 ```
 flake8_elegant_objects/
-├── __init__.py          # Main plugin entry point
-├── base.py              # Base classes and utilities
-├── no_er_name.py        # EO001-EO004: No "-er" names
-├── no_null.py           # EO005: No None usage
-├── no_constructor_code.py # EO006: No code in constructors
-├── no_getters_setters.py  # EO007: No getters/setters
-├── no_mutable_objects.py  # EO008: No mutable objects
-├── no_static.py         # EO009: No static methods
-├── no_type_discrimination.py # EO010: No isinstance/type casting
-├── no_public_methods_without_contracts.py # EO011: Contracts required
-├── no_impure_tests.py   # EO012: Only assertThat in tests
-├── no_orm.py            # EO013: No ORM/ActiveRecord
-└── no_implementation_inheritance.py # EO014: No implementation inheritance
+├── __init__.py              # Main plugin entry point
+├── __main__.py              # CLI interface
+├── base.py                  # Core types, error codes, and base classes
+├── no_constructor_code.py   # EO006: No code in constructors
+├── no_er_name.py           # EO001-EO004: No -er naming violations
+├── no_getters_setters.py   # EO007: No getter/setter methods
+├── no_implementation_inheritance.py  # EO014: No implementation inheritance
+├── no_impure_tests.py      # EO012: Test methods with single assertions
+├── no_null.py              # EO005: No None/null usage
+├── no_orm.py               # EO013: No ORM/ActiveRecord patterns
+├── no_public_methods_without_contracts.py  # EO011: Methods need contracts
+├── no_static.py            # EO009: No static methods
+├── no_type_discrimination.py  # EO010: No isinstance/type casting
+└── no_mutable_objects/     # EO008, EO015-EO027: Comprehensive mutability detection
+    ├── __init__.py         # Package initialization
+    ├── base.py             # Shared utilities and state tracking
+    ├── core.py             # Main orchestrator for all mutable object checks
+    ├── contract_checker.py # EO024: Immutability contract enforcement
+    ├── copy_on_write_checker.py  # EO025: Copy-on-write pattern validation
+    ├── deep_checker.py     # Cross-class mutation analysis
+    ├── factory_checker.py  # EO022: Factory method pattern validation
+    ├── pattern_detectors.py # EO026-EO027: Aliasing and defensive copy detection
+    └── shared_state_checker.py  # EO023: Shared mutable state detection
 ```

{flake8_elegant_objects-1.0.0 → flake8_elegant_objects-1.1.0}/README.md

@@ -1,25 +1,45 @@
 # Flake8 ElegantObjects Plugin
 
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/AntonProkopyev/flake8-elegant-objects)
-[![Coverage](https://img.shields.io/badge/coverage-86%25-brightgreen.svg)](https://github.com/AntonProkopyev/flake8-elegant-objects)
+[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)](https://github.com/AntonProkopyev/flake8-elegant-objects)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Type checked: mypy](https://img.shields.io/badge/type_checked-mypy-blue.svg)](https://mypy.readthedocs.io/)
 [![Flake8](https://img.shields.io/badge/flake8-plugin-orange.svg)](https://flake8.pycqa.org/)
 
-Detects violations of core Elegant Objects principles including the "-er" naming principle, null usage, mutable objects, code in constructors, and getter/setter patterns.
+Detects violations of [Elegant Objects principles](https://www.elegantobjects.org/) including the "-er" naming principle, null usage, mutable objects, code in constructors, and getter/setter patterns.
 
 ## Error Codes
 
+### Naming Violations (EO001-EO004)
 - `EO001`: Class name violates -er principle
 - `EO002`: Method name violates -er principle
 - `EO003`: Variable name violates -er principle
 - `EO004`: Function name violates -er principle
+
+### Object Behavior (EO005-EO007)
 - `EO005`: Null (None) usage violates EO principle
 - `EO006`: Code in constructor violates EO principle
 - `EO007`: Getter/setter method violates EO principle
-- `EO008`: Mutable object violation
+
+### Mutable Object Violations (EO008, EO015-EO027)
+- `EO008`: Mutable dataclass violation
+- `EO015`: Mutable class attribute violation
+- `EO016`: Mutable instance attribute violation
+- `EO017`: Instance attribute mutation violation
+- `EO018`: Augmented assignment mutation violation
+- `EO019`: Mutating method call violation
+- `EO020`: Subscript assignment mutation violation
+- `EO021`: Chained mutation violation
+- `EO022`: Missing factory methods violation
+- `EO023`: Mutable default argument violation
+- `EO024`: Missing immutability enforcement violation
+- `EO025`: Copy-on-write violation
+- `EO026`: Aliasing violation (exposing mutable state)
+- `EO027`: Defensive copy violation
+
+### Design and Architecture (EO009-EO014)
 - `EO009`: Static method violates EO principle (no static methods allowed)
 - `EO010`: isinstance/type casting violates EO principle (avoid type discrimination)
 - `EO011`: Public method without contract (Protocol/ABC) violates EO principle
@@ -52,7 +72,7 @@ The plugin is automatically registered when the package is installed.
 
 ## Philosophy
 
-Based on Yegor Bugayenko's Elegant Objects principles, this plugin enforces object-oriented design that treats objects as living, thinking entities rather than data containers or procedure executors.
+Based on [Yegor Bugayenko](https://www.yegor256.com/)'s [Elegant Objects principles](https://www.elegantobjects.org/), this plugin enforces object-oriented design that treats objects as living, thinking entities rather than data containers or procedure executors.
 
 ### 1. No "-er" Entities (EO001-EO004)
 
@@ -83,12 +103,26 @@ Based on Yegor Bugayenko's Elegant Objects principles, this plugin enforces obje
 - ❌ `def get_value()` / `def set_value()` → ✅ Objects should expose behavior, not data
 - ❌ `user.getName()` → ✅ `user.introduce_yourself()` or `user.greet(visitor)`
 
-### 5. No Mutable Objects (EO008)
+### 5. No Mutable Objects (EO008, EO015-EO027)
+
+**Why?** Mutable objects introduce temporal coupling and make reasoning about code difficult. Immutable objects are thread-safe, predictable, and easier to test. This plugin provides comprehensive detection of various mutability patterns.
+
+**Basic Mutability Issues:**
+- ❌ `@dataclass class Data` → ✅ `@dataclass(frozen=True) class Data` *(EO008)*
+- ❌ `items = []` (class attribute) → ✅ `items: tuple = ()` *(EO015)*
+- ❌ `self.data = []` (instance attribute) → ✅ `self.data: tuple = ()` *(EO016)*
 
-**Why?** Mutable objects introduce temporal coupling and make reasoning about code difficult. Immutable objects are thread-safe, predictable, and easier to test.
+**Mutation Patterns:**
+- ❌ `self.items.append(x)` → ✅ `self.items = (*self.items, x)` *(EO019)*
+- ❌ `self.count += 1` → ✅ `return Counter(self.count + 1)` *(EO018)*
+- ❌ `self.data[key] = value` → ✅ Use immutable data structures *(EO020)*
+- ❌ `self.data = new_value` (after init) → ✅ Return new instance *(EO017)*
 
-- ❌ `@dataclass class Data` → ✅ `@dataclass(frozen=True) class Data`
-- ❌ `items = []` → ✅ `items: tuple = ()`
+**Advanced Patterns:**
+- ❌ `def items=[]:` (mutable defaults) → ✅ `def items=None:` + null object *(EO023)*
+- ❌ `return self._items` (exposing mutable state) → ✅ `return tuple(self._items)` *(EO026)*
+- ❌ `self.items = items` (no defensive copy) → ✅ `self.items = tuple(items)` *(EO027)*
+- ❌ Class with mutable state but no factory methods → ✅ Provide immutable factory methods *(EO022)*
 
 ### 6. No Static Methods (EO009)
 
@@ -170,17 +204,27 @@ ruff format flake8_elegant_objects/
 
 ```
 flake8_elegant_objects/
-├── __init__.py          # Main plugin entry point
-├── base.py              # Base classes and utilities
-├── no_er_name.py        # EO001-EO004: No "-er" names
-├── no_null.py           # EO005: No None usage
-├── no_constructor_code.py # EO006: No code in constructors
-├── no_getters_setters.py  # EO007: No getters/setters
-├── no_mutable_objects.py  # EO008: No mutable objects
-├── no_static.py         # EO009: No static methods
-├── no_type_discrimination.py # EO010: No isinstance/type casting
-├── no_public_methods_without_contracts.py # EO011: Contracts required
-├── no_impure_tests.py   # EO012: Only assertThat in tests
-├── no_orm.py            # EO013: No ORM/ActiveRecord
-└── no_implementation_inheritance.py # EO014: No implementation inheritance
+├── __init__.py              # Main plugin entry point
+├── __main__.py              # CLI interface
+├── base.py                  # Core types, error codes, and base classes
+├── no_constructor_code.py   # EO006: No code in constructors
+├── no_er_name.py           # EO001-EO004: No -er naming violations
+├── no_getters_setters.py   # EO007: No getter/setter methods
+├── no_implementation_inheritance.py  # EO014: No implementation inheritance
+├── no_impure_tests.py      # EO012: Test methods with single assertions
+├── no_null.py              # EO005: No None/null usage
+├── no_orm.py               # EO013: No ORM/ActiveRecord patterns
+├── no_public_methods_without_contracts.py  # EO011: Methods need contracts
+├── no_static.py            # EO009: No static methods
+├── no_type_discrimination.py  # EO010: No isinstance/type casting
+└── no_mutable_objects/     # EO008, EO015-EO027: Comprehensive mutability detection
+    ├── __init__.py         # Package initialization
+    ├── base.py             # Shared utilities and state tracking
+    ├── core.py             # Main orchestrator for all mutable object checks
+    ├── contract_checker.py # EO024: Immutability contract enforcement
+    ├── copy_on_write_checker.py  # EO025: Copy-on-write pattern validation
+    ├── deep_checker.py     # Cross-class mutation analysis
+    ├── factory_checker.py  # EO022: Factory method pattern validation
+    ├── pattern_detectors.py # EO026-EO027: Aliasing and defensive copy detection
+    └── shared_state_checker.py  # EO023: Shared mutable state detection
 ```

{flake8_elegant_objects-1.0.0 → flake8_elegant_objects-1.1.0}/flake8_elegant_objects/base.py

@@ -21,7 +21,7 @@ class ErrorCodes:
     EO005 = "EO005 Null (None) usage violates EO principle (avoid None)"
     EO006 = "EO006 Code in constructor violates EO principle (constructors should only assign parameters)"
     EO007 = "EO007 Getter/setter method '{name}' violates EO principle (avoid getters/setters)"
-    EO008 = "EO008 Mutable object violation: '{name}' should be immutable"
+    EO008 = "EO008 Mutable dataclass violation: {name}"
     EO009 = (
         "EO009 Static method '{name}' violates EO principle (no static methods allowed)"
     )
@@ -30,6 +30,19 @@ class ErrorCodes:
     EO012 = "EO012 Test method '{name}' contains non-assertThat statements (only assertThat allowed)"
     EO013 = "EO013 ORM/ActiveRecord pattern '{name}' violates EO principle"
     EO014 = "EO014 Implementation inheritance violates EO principle (class '{name}' inherits from non-abstract class)"
+    EO015 = "EO015 Mutable class attribute violation: {name}"
+    EO016 = "EO016 Mutable instance attribute violation: {name}"
+    EO017 = "EO017 Instance attribute mutation violation: {name}"
+    EO018 = "EO018 Augmented assignment mutation violation: {name}"
+    EO019 = "EO019 Mutating method call violation: {name}"
+    EO020 = "EO020 Subscript assignment mutation violation: {name}"
+    EO021 = "EO021 Chained mutation violation: {name}"
+    EO022 = "EO022 Missing factory methods violation: {name}"
+    EO023 = "EO023 Mutable default argument violation: {name}"
+    EO024 = "EO024 Missing immutability enforcement violation: {name}"
+    EO025 = "EO025 Copy-on-write violation: {name}"
+    EO026 = "EO026 Aliasing violation (exposing mutable state): {name}"
+    EO027 = "EO027 Defensive copy violation: {name}"
 
 
 class Violation:
@@ -101,7 +114,7 @@ def is_method(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
     """Check if function is a method (has self parameter)."""
     if not node.args.args:
         return False
-    return node.args.args[0].arg in ("self", "cls")
+    return node.args.args[0].arg in {"self", "cls"}
 
 
 def get_all_principles() -> list[Principle]:
@@ -139,6 +152,15 @@ class ElegantObjectsCore:
 
     def __init__(self, tree: ast.AST) -> None:
         self.tree = tree
+        self._parent_map: dict[ast.AST, ast.AST | None] = {}
+        self._build_parent_map(tree, None)
+
+    def _build_parent_map(self, node: ast.AST, parent: ast.AST | None) -> None:
+        """Build a map of nodes to their parents for better context."""
+        if parent:
+            setattr(node, "_parent", parent)  # noqa: B010
+        for child in ast.iter_child_nodes(node):
+            self._build_parent_map(child, node)
 
     def check_violations(self) -> list[Violation]:
         """Check for all violations in the AST tree."""
@@ -156,10 +178,8 @@ class ElegantObjectsCore:
         if isinstance(node, ast.ClassDef):
             current_class = node
 
-        # Check principles on current node
         violations.extend(self._check_principles(node, current_class))
 
-        # Visit child nodes
         for child in ast.iter_child_nodes(node):
             violations.extend(self._visit(child, current_class))
 

{flake8_elegant_objects-1.0.0 → flake8_elegant_objects-1.1.0}/flake8_elegant_objects/no_er_name.py

@@ -233,7 +233,7 @@ class NoErName:
             return []
 
         # Skip common property patterns
-        if node.name in ("property", "getter", "setter"):
+        if node.name in {"property", "getter", "setter"}:
             return []
 
         # Check for procedural verbs