tapps-agents 3.6.0__py3-none-any.whl → 3.6.1__py3-none-any.whl

tapps_agents/experts/knowledge/code-quality-analysis/code-metrics.md

@@ -1,137 +1,137 @@
-# Code Metrics
-
-## Overview
-
-Code metrics provide quantitative measurements of code quality, complexity, and maintainability. These metrics help identify areas needing improvement and track quality trends over time.
-
-## Core Metrics
-
-### Cyclomatic Complexity
-
-Measures the number of linearly independent paths through a program's source code.
-
-**Thresholds:**
-- **1-10**: Simple (low risk)
-- **11-20**: Moderate (moderate risk)
-- **21-50**: Complex (high risk)
-- **50+**: Very complex (very high risk)
-
-**Reduction Strategies:**
-- Extract methods for complex conditionals
-- Use polymorphism instead of switch statements
-- Break down large functions
-- Apply design patterns (Strategy, Command)
-
-### Maintainability Index
-
-Composite metric based on:
-- Halstead Volume
-- Cyclomatic Complexity
-- Lines of Code
-
-**Scale:** 0-100 (higher is better)
-- **20-40**: Difficult to maintain
-- **40-60**: Moderate maintainability
-- **60-80**: Good maintainability
-- **80-100**: Excellent maintainability
-
-### Lines of Code (LOC)
-
-**Best Practices:**
-- Methods: < 20 lines
-- Classes: < 300 lines
-- Files: < 500 lines
-- Modules: < 1000 lines
-
-### Code Duplication
-
-**Thresholds:**
-- **0-3%**: Excellent
-- **3-5%**: Good
-- **5-10%**: Acceptable
-- **10%+**: Needs refactoring
-
-**DRY Principle:**
-- Don't Repeat Yourself
-- Extract common functionality
-- Use abstractions and inheritance
-
-### Test Coverage
-
-**Coverage Types:**
-- **Line Coverage**: % of lines executed
-- **Branch Coverage**: % of branches tested
-- **Function Coverage**: % of functions called
-
-**Targets:**
-- **80%+**: Good coverage
-- **90%+**: Excellent coverage
-- **100%**: Perfect (but may be overkill)
-
-## Advanced Metrics
-
-### Technical Debt Ratio
-
-```
-Technical Debt Ratio = (Remediation Cost / Development Cost) × 100
-```
-
-**Interpretation:**
-- **< 5%**: Low technical debt
-- **5-10%**: Moderate technical debt
-- **10-20%**: Significant technical debt
-- **20%+**: Critical technical debt
-
-### Code Churn
-
-Measures how frequently code changes.
-
-**High Churn Indicators:**
-- Frequently modified files
-- Unstable areas of code
-- Potential architectural issues
-
-### Coupling Metrics
-
-**Afferent Coupling (Ca):** Number of classes outside a package that depend on classes within it.
-
-**Efferent Coupling (Ce):** Number of classes inside a package that depend on classes outside it.
-
-**Instability (I):** I = Ce / (Ca + Ce)
-- **0**: Stable (no dependencies on external classes)
-- **1**: Instable (depends on external classes)
-
-## Metrics Collection Tools
-
-### Python
-- **radon**: Complexity metrics
-- **coverage.py**: Test coverage
-- **vulture**: Dead code detection
-- **pylint**: Code quality scoring
-
-### JavaScript/TypeScript
-- **complexity-report**: Cyclomatic complexity
-- **istanbul/nyc**: Coverage
-- **escomplex**: Code complexity
-
-### Multi-Language
-- **SonarQube**: Comprehensive metrics platform
-- **CodeClimate**: Automated code review
-- **Better Code Hub**: Quality assessment
-
-## Using Metrics Effectively
-
-1. **Set Baseline**: Measure current state
-2. **Define Targets**: Set improvement goals
-3. **Track Trends**: Monitor over time
-4. **Prioritize**: Focus on high-impact areas
-5. **Automate**: Integrate into CI/CD
-6. **Review Regularly**: Monthly/quarterly assessments
-
-## Anti-Patterns to Avoid
-
-- **Metrics Obsession**: Don't optimize for metrics alone
-- **False Positives**: Understand context before acting
-- **Ignoring Context**: Metrics without understanding are useless
-- **Gaming Metrics**: Don't artificially improve numbers
-- **One-Size-Fits-All**: Different projects need different thresholds
+# Code Metrics
+
+## Overview
+
+Code metrics provide quantitative measurements of code quality, complexity, and maintainability. These metrics help identify areas needing improvement and track quality trends over time.
+
+## Core Metrics
+
+### Cyclomatic Complexity
+
+Measures the number of linearly independent paths through a program's source code.
+
+**Thresholds:**
+- **1-10**: Simple (low risk)
+- **11-20**: Moderate (moderate risk)
+- **21-50**: Complex (high risk)
+- **50+**: Very complex (very high risk)
+
+**Reduction Strategies:**
+- Extract methods for complex conditionals
+- Use polymorphism instead of switch statements
+- Break down large functions
+- Apply design patterns (Strategy, Command)
+
+### Maintainability Index
+
+Composite metric based on:
+- Halstead Volume
+- Cyclomatic Complexity
+- Lines of Code
+
+**Scale:** 0-100 (higher is better)
+- **20-40**: Difficult to maintain
+- **40-60**: Moderate maintainability
+- **60-80**: Good maintainability
+- **80-100**: Excellent maintainability
+
+### Lines of Code (LOC)
+
+**Best Practices:**
+- Methods: < 20 lines
+- Classes: < 300 lines
+- Files: < 500 lines
+- Modules: < 1000 lines
+
+### Code Duplication
+
+**Thresholds:**
+- **0-3%**: Excellent
+- **3-5%**: Good
+- **5-10%**: Acceptable
+- **10%+**: Needs refactoring
+
+**DRY Principle:**
+- Don't Repeat Yourself
+- Extract common functionality
+- Use abstractions and inheritance
+
+### Test Coverage
+
+**Coverage Types:**
+- **Line Coverage**: % of lines executed
+- **Branch Coverage**: % of branches tested
+- **Function Coverage**: % of functions called
+
+**Targets:**
+- **80%+**: Good coverage
+- **90%+**: Excellent coverage
+- **100%**: Perfect (but may be overkill)
+
+## Advanced Metrics
+
+### Technical Debt Ratio
+
+```
+Technical Debt Ratio = (Remediation Cost / Development Cost) × 100
+```
+
+**Interpretation:**
+- **< 5%**: Low technical debt
+- **5-10%**: Moderate technical debt
+- **10-20%**: Significant technical debt
+- **20%+**: Critical technical debt
+
+### Code Churn
+
+Measures how frequently code changes.
+
+**High Churn Indicators:**
+- Frequently modified files
+- Unstable areas of code
+- Potential architectural issues
+
+### Coupling Metrics
+
+**Afferent Coupling (Ca):** Number of classes outside a package that depend on classes within it.
+
+**Efferent Coupling (Ce):** Number of classes inside a package that depend on classes outside it.
+
+**Instability (I):** I = Ce / (Ca + Ce)
+- **0**: Stable (no dependencies on external classes)
+- **1**: Instable (depends on external classes)
+
+## Metrics Collection Tools
+
+### Python
+- **radon**: Complexity metrics
+- **coverage.py**: Test coverage
+- **vulture**: Dead code detection
+- **pylint**: Code quality scoring
+
+### JavaScript/TypeScript
+- **complexity-report**: Cyclomatic complexity
+- **istanbul/nyc**: Coverage
+- **escomplex**: Code complexity
+
+### Multi-Language
+- **SonarQube**: Comprehensive metrics platform
+- **CodeClimate**: Automated code review
+- **Better Code Hub**: Quality assessment
+
+## Using Metrics Effectively
+
+1. **Set Baseline**: Measure current state
+2. **Define Targets**: Set improvement goals
+3. **Track Trends**: Monitor over time
+4. **Prioritize**: Focus on high-impact areas
+5. **Automate**: Integrate into CI/CD
+6. **Review Regularly**: Monthly/quarterly assessments
+
+## Anti-Patterns to Avoid
+
+- **Metrics Obsession**: Don't optimize for metrics alone
+- **False Positives**: Understand context before acting
+- **Ignoring Context**: Metrics without understanding are useless
+- **Gaming Metrics**: Don't artificially improve numbers
+- **One-Size-Fits-All**: Different projects need different thresholds

tapps_agents/experts/knowledge/code-quality-analysis/complexity-analysis.md

@@ -1,181 +1,181 @@
-# Complexity Analysis
-
-## What is Code Complexity?
-
-Code complexity measures how difficult code is to understand, test, and maintain. High complexity increases the likelihood of bugs and makes code harder to modify.
-
-## Types of Complexity
-
-### Cyclomatic Complexity
-
-Measures the number of linearly independent paths through program code.
-
-**Formula:**
-```
-M = E - N + 2P
-```
-Where:
-- E = Number of edges (flow graph connections)
-- N = Number of nodes (statements)
-- P = Number of connected components
-
-**Python Example:**
-```python
-# Low complexity (M = 2)
-def is_even(n):
-    return n % 2 == 0
-
-# Medium complexity (M = 4)
-def categorize_age(age):
-    if age < 13:
-        return "child"
-    elif age < 20:
-        return "teenager"
-    elif age < 65:
-        return "adult"
-    else:
-        return "senior"
-
-# High complexity (M = 8+)
-def process_user(user, permissions, role, context):
-    if user.is_active:
-        if permissions.has_access:
-            if role == "admin":
-                if context.is_secure:
-                    # ... many nested conditions
-                    return result
-```
-
-### Cognitive Complexity
-
-Measures how difficult code is to understand by humans, focusing on readability rather than testability.
-
-**Factors:**
-- Nesting levels
-- Logical operators (AND, OR)
-- Recursion
-- Control flow structures
-
-### Time Complexity (Big O)
-
-Measures how algorithm runtime scales with input size.
-
-**Common Complexities:**
-- **O(1)**: Constant time (best)
-- **O(log n)**: Logarithmic (excellent)
-- **O(n)**: Linear (good)
-- **O(n log n)**: Linearithmic (acceptable)
-- **O(n²)**: Quadratic (poor)
-- **O(2ⁿ)**: Exponential (very poor)
-
-### Space Complexity
-
-Measures memory usage relative to input size.
-
-## Reducing Complexity
-
-### Strategy Pattern
-Replace complex conditionals with strategy objects.
-
-```python
-# Before: High complexity
-def calculate_shipping(country, weight, method):
-    if country == "US":
-        if method == "standard":
-            if weight < 1:
-                return 5.00
-            elif weight < 5:
-                return 10.00
-            # ... many nested conditions
-
-# After: Lower complexity
-class ShippingCalculator:
-    def calculate(self, country, weight, method):
-        strategy = self._get_strategy(country, method)
-        return strategy.calculate(weight)
-```
-
-### Extract Methods
-Break large functions into smaller ones.
-
-```python
-# Before: Complex function
-def process_order(order):
-    # 50+ lines of code with multiple responsibilities
-    pass
-
-# After: Simpler functions
-def process_order(order):
-    validate_order(order)
-    calculate_totals(order)
-    apply_discounts(order)
-    process_payment(order)
-    send_confirmation(order)
-```
-
-### Early Returns
-Reduce nesting with early exit conditions.
-
-```python
-# Before: Nested conditions
-def process_user(user):
-    if user:
-        if user.is_active:
-            if user.has_permissions:
-                # Main logic here
-                return result
-    return None
-
-# After: Early returns
-def process_user(user):
-    if not user or not user.is_active:
-        return None
-    if not user.has_permissions:
-        return None
-    # Main logic here
-    return result
-```
-
-## Complexity Metrics
-
-### Acceptable Thresholds
-
-| Metric | Excellent | Good | Acceptable | Poor |
-|--------|-----------|------|------------|------|
-| Cyclomatic Complexity | 1-5 | 6-10 | 11-20 | 21+ |
-| Cognitive Complexity | 1-5 | 6-10 | 11-15 | 16+ |
-| Function Length (LOC) | < 20 | 20-50 | 50-100 | 100+ |
-| Nesting Depth | 1-2 | 3 | 4 | 5+ |
-
-### Warning Signs
-
-1. **High Cyclomatic Complexity**: Many conditional paths
-2. **Deep Nesting**: 4+ levels of indentation
-3. **Long Functions**: 100+ lines
-4. **Many Parameters**: 5+ function parameters
-5. **God Classes**: 1000+ lines per class
-
-## Tools for Analysis
-
-### Python
-- **radon**: Complexity metrics
-- **mccabe**: Cyclomatic complexity
-- **xenon**: Complexity monitoring
-
-### JavaScript/TypeScript
-- **complexity-report**: Code complexity
-- **escomplex**: Complexity analysis
-
-### Multi-Language
-- **SonarQube**: Comprehensive analysis
-- **CodeClimate**: Complexity scoring
-
-## Best Practices
-
-1. **Keep Functions Small**: Single responsibility
-2. **Limit Nesting**: Maximum 3-4 levels
-3. **Use Early Returns**: Reduce nesting
-4. **Extract Methods**: Break down complex logic
-5. **Apply Patterns**: Strategy, Command, Factory
-6. **Refactor Regularly**: Continuously improve
-7. **Set Thresholds**: Enforce in CI/CD
+# Complexity Analysis
+
+## What is Code Complexity?
+
+Code complexity measures how difficult code is to understand, test, and maintain. High complexity increases the likelihood of bugs and makes code harder to modify.
+
+## Types of Complexity
+
+### Cyclomatic Complexity
+
+Measures the number of linearly independent paths through program code.
+
+**Formula:**
+```
+M = E - N + 2P
+```
+Where:
+- E = Number of edges (flow graph connections)
+- N = Number of nodes (statements)
+- P = Number of connected components
+
+**Python Example:**
+```python
+# Low complexity (M = 2)
+def is_even(n):
+    return n % 2 == 0
+
+# Medium complexity (M = 4)
+def categorize_age(age):
+    if age < 13:
+        return "child"
+    elif age < 20:
+        return "teenager"
+    elif age < 65:
+        return "adult"
+    else:
+        return "senior"
+
+# High complexity (M = 8+)
+def process_user(user, permissions, role, context):
+    if user.is_active:
+        if permissions.has_access:
+            if role == "admin":
+                if context.is_secure:
+                    # ... many nested conditions
+                    return result
+```
+
+### Cognitive Complexity
+
+Measures how difficult code is to understand by humans, focusing on readability rather than testability.
+
+**Factors:**
+- Nesting levels
+- Logical operators (AND, OR)
+- Recursion
+- Control flow structures
+
+### Time Complexity (Big O)
+
+Measures how algorithm runtime scales with input size.
+
+**Common Complexities:**
+- **O(1)**: Constant time (best)
+- **O(log n)**: Logarithmic (excellent)
+- **O(n)**: Linear (good)
+- **O(n log n)**: Linearithmic (acceptable)
+- **O(n²)**: Quadratic (poor)
+- **O(2ⁿ)**: Exponential (very poor)
+
+### Space Complexity
+
+Measures memory usage relative to input size.
+
+## Reducing Complexity
+
+### Strategy Pattern
+Replace complex conditionals with strategy objects.
+
+```python
+# Before: High complexity
+def calculate_shipping(country, weight, method):
+    if country == "US":
+        if method == "standard":
+            if weight < 1:
+                return 5.00
+            elif weight < 5:
+                return 10.00
+            # ... many nested conditions
+
+# After: Lower complexity
+class ShippingCalculator:
+    def calculate(self, country, weight, method):
+        strategy = self._get_strategy(country, method)
+        return strategy.calculate(weight)
+```
+
+### Extract Methods
+Break large functions into smaller ones.
+
+```python
+# Before: Complex function
+def process_order(order):
+    # 50+ lines of code with multiple responsibilities
+    pass
+
+# After: Simpler functions
+def process_order(order):
+    validate_order(order)
+    calculate_totals(order)
+    apply_discounts(order)
+    process_payment(order)
+    send_confirmation(order)
+```
+
+### Early Returns
+Reduce nesting with early exit conditions.
+
+```python
+# Before: Nested conditions
+def process_user(user):
+    if user:
+        if user.is_active:
+            if user.has_permissions:
+                # Main logic here
+                return result
+    return None
+
+# After: Early returns
+def process_user(user):
+    if not user or not user.is_active:
+        return None
+    if not user.has_permissions:
+        return None
+    # Main logic here
+    return result
+```
+
+## Complexity Metrics
+
+### Acceptable Thresholds
+
+| Metric | Excellent | Good | Acceptable | Poor |
+|--------|-----------|------|------------|------|
+| Cyclomatic Complexity | 1-5 | 6-10 | 11-20 | 21+ |
+| Cognitive Complexity | 1-5 | 6-10 | 11-15 | 16+ |
+| Function Length (LOC) | < 20 | 20-50 | 50-100 | 100+ |
+| Nesting Depth | 1-2 | 3 | 4 | 5+ |
+
+### Warning Signs
+
+1. **High Cyclomatic Complexity**: Many conditional paths
+2. **Deep Nesting**: 4+ levels of indentation
+3. **Long Functions**: 100+ lines
+4. **Many Parameters**: 5+ function parameters
+5. **God Classes**: 1000+ lines per class
+
+## Tools for Analysis
+
+### Python
+- **radon**: Complexity metrics
+- **mccabe**: Cyclomatic complexity
+- **xenon**: Complexity monitoring
+
+### JavaScript/TypeScript
+- **complexity-report**: Code complexity
+- **escomplex**: Complexity analysis
+
+### Multi-Language
+- **SonarQube**: Comprehensive analysis
+- **CodeClimate**: Complexity scoring
+
+## Best Practices
+
+1. **Keep Functions Small**: Single responsibility
+2. **Limit Nesting**: Maximum 3-4 levels
+3. **Use Early Returns**: Reduce nesting
+4. **Extract Methods**: Break down complex logic
+5. **Apply Patterns**: Strategy, Command, Factory
+6. **Refactor Regularly**: Continuously improve
+7. **Set Thresholds**: Enforce in CI/CD