moai-adk 0.32.8__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-workflow-testing/modules/automated-code-review/trust5-framework/usability-analysis.md

@@ -0,0 +1,153 @@
+# Usability Analysis - TRUST 5 Framework
+
+> Module: Usability category deep dive with maintainability metrics and code organization
+> Parent: [TRUST 5 Framework](./trust5-framework.md)
+> Complexity: Advanced
+> Time: 15+ minutes
+> Dependencies: Python 3.8+, ast, math
+
+## Overview
+
+Usability (25% weight) assesses maintainability and understandability through code organization evaluation, documentation quality measurement, complexity metrics calculation, and naming convention validation.
+
+## Advanced Maintainability Metrics
+
+### Halstead Complexity Metrics
+
+```python
+def _calculate_halstead_metrics(
+    self, content: str, tree: ast.AST
+) -> Dict[str, float]:
+    """Calculate Halstead complexity metrics."""
+
+    # Count operators and operands
+    operators = set()
+    operands = set()
+    total_operators = 0
+    total_operands = 0
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.BinOp):
+            operators.add(type(node.op).__name__)
+            total_operators += 1
+        elif isinstance(node, ast.BoolOp):
+            operators.add(type(node.op).__name__)
+            total_operators += 1
+        elif isinstance(node, ast.Name):
+            operands.add(node.id)
+            total_operands += 1
+
+    n1 = len(operators)  # Unique operators
+    n2 = len(operands)  # Unique operands
+    N1 = total_operators  # Total operators
+    N2 = total_operands  # Total operands
+
+    # Calculate Halstead metrics
+    program_length = n1 + n2
+    vocabulary = n1 * math.log2(n1) + n2 * math.log2(n2) if n1 > 0 and n2 > 0 else 0
+    volume = vocabulary * math.log2(vocabulary) if vocabulary > 0 else 0
+    difficulty = (n1 / 2) * (N2 / n2) if n2 > 0 else 0
+    effort = difficulty * volume
+    time_required = effort / 18  # Seconds
+    bugs_delivered = effort / 3000  # Estimated bugs
+
+    return {
+        'program_length': program_length,
+        'vocabulary': vocabulary,
+        'volume': volume,
+        'difficulty': difficulty,
+        'effort': effort,
+        'time_required': time_required,
+        'bugs_delivered': bugs_delivered
+    }
+```
+
+### Comprehensive Maintainability Calculation
+
+```python
+def calculate_advanced_maintainability(
+    self, file_path: str, content: str, tree: ast.AST
+) -> Dict[str, Any]:
+    """Calculate advanced maintainability metrics."""
+
+    metrics = {}
+
+    # Calculate Halstead metrics
+    halstead = self._calculate_halstead_metrics(content, tree)
+    metrics['halstead'] = halstead
+
+    # Calculate Maintainability Index
+    mi = self._calculate_maintainability_index(halstead, tree)
+    metrics['maintainability_index'] = mi
+
+    # Calculate coupling
+    coupling = self._calculate_coupling(tree)
+    metrics['coupling'] = coupling
+
+    # Calculate cohesion
+    cohesion = self._calculate_cohesion(tree)
+    metrics['cohesion'] = cohesion
+
+    return metrics
+```
+
+## Code Organization Assessment
+
+### Structural Analysis
+
+```python
+def assess_code_organization(self, file_path: str, tree: ast.AST) -> List[CodeIssue]:
+    """Assess code organization and structure."""
+
+    issues = []
+
+    # Check for circular dependencies
+    circular_deps = self._detect_circular_dependencies(tree)
+    issues.extend(circular_deps)
+
+    # Check for poor separation of concerns
+    separation_issues = self._check_separation_of_concerns(tree)
+    issues.extend(separation_issues)
+
+    # Check for inconsistent code style
+    style_issues = self._check_code_consistency(tree)
+    issues.extend(style_issues)
+
+    return issues
+```
+
+## Detection Patterns
+
+### Common Usability Issues
+
+1. **High Complexity**: Functions/classes exceeding complexity thresholds
+2. **Poor Naming**: Non-descriptive variable/function names
+3. **Long Functions**: Functions exceeding length limits
+4. **Deep Nesting**: Excessive indentation levels
+5. **Magic Numbers**: Unnamed constants in code
+6. **Duplicate Code**: Similar code blocks repeated
+7. **Poor Documentation**: Missing or unclear docstrings
+
+### Context7 Integration
+
+```python
+# Load usability patterns
+usability = await self.context7.get_library_docs(
+    context7_library_id="/code-quality/sonarqube",
+    topic="maintainability metrics code smells 2025",
+    tokens=4000
+)
+```
+
+## Best Practices
+
+1. Metric Thresholds: Establish project-specific complexity thresholds
+2. Naming Conventions: Enforce consistent naming patterns
+3. Documentation Standards: Require docstrings for public APIs
+4. Code Review: Use metrics to guide code review focus
+5. Refactoring: Track metric improvements over time
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06

moai_adk/templates/.claude/skills/moai-workflow-testing/modules/automated-code-review/trust5-framework.md

@@ -0,0 +1,257 @@
+# TRUST 5 Framework Deep Dive
+
+> Module: Advanced TRUST 5 methodology with category-specific analysis patterns
+> Parent: [TRUST 5 Validation](../trust5-validation.md)
+> Complexity: Advanced
+> Time: 25+ minutes
+> Dependencies: Python 3.8+, Context7 MCP, ast
+
+## Quick Reference
+
+### TRUST 5 Methodology
+
+TRUST 5 Framework provides comprehensive code quality assessment across five essential dimensions:
+
+**Truthfulness (25%)**: Code correctness and logic accuracy
+- Validates algorithmic correctness
+- Detects logic errors and unreachable code
+- Ensures data flow integrity
+- Verifies contract compliance
+- See: [Truthfulness Analysis](./trust5-framework/truthfulness-analysis.md)
+
+**Relevance (20%)**: Requirements fulfillment and purpose alignment
+- Confirms feature completeness
+- Validates requirements traceability
+- Identifies dead code
+- Checks purpose alignment
+- See: [Relevance Analysis](./trust5-framework/relevance-analysis.md)
+
+**Usability (25%)**: Maintainability and understandability
+- Assesses code organization
+- Evaluates documentation quality
+- Measures complexity metrics
+- Validates naming conventions
+- See: [Usability Analysis](./trust5-framework/usability-analysis.md)
+
+**Safety (20%)**: Security and error handling
+- Detects security vulnerabilities
+- Validates error handling
+- Ensures resource safety
+- Checks input validation
+- See: [Safety Analysis](./trust5-framework/safety-analysis.md)
+
+**Timeliness (10%)**: Performance and modern practices
+- Identifies optimization opportunities
+- Detects deprecated code
+- Validates performance standards
+- Checks technology currency
+- See: [Timeliness Analysis](./trust5-framework/timeliness-analysis.md)
+
+### Category-Specific Analysis Patterns
+
+```python
+class AdvancedTRUST5Analyzer:
+    """Advanced TRUST 5 analyzer with category-specific patterns."""
+
+    def __init__(self, context7_client=None):
+        self.context7 = context7_client
+        self.category_patterns = {}
+
+    async def load_category_patterns(self) -> Dict[str, Any]:
+        """Load category-specific analysis patterns from Context7."""
+
+        if not self.context7:
+            return self._get_default_patterns()
+
+        try:
+            # Load truthfulness patterns
+            truthfulness = await self.context7.get_library_docs(
+                context7_library_id="/code-correctness/python",
+                topic="logic error detection patterns 2025",
+                tokens=3000
+            )
+
+            # Load usability patterns
+            usability = await self.context7.get_library_docs(
+                context7_library_id="/code-quality/sonarqube",
+                topic="maintainability metrics code smells 2025",
+                tokens=4000
+            )
+
+            # Load safety patterns
+            safety = await self.context7.get_library_docs(
+                context7_library_id="/security/owasp",
+                topic="security vulnerability detection 2025",
+                tokens=5000
+            )
+
+            return {
+                'truthfulness': truthfulness,
+                'usability': usability,
+                'safety': safety
+            }
+
+        except Exception as e:
+            return self._get_default_patterns()
+```
+
+---
+
+## Category Analysis Overview
+
+### Truthfulness Analysis
+
+**Purpose**: Validates code correctness and logic accuracy
+
+**Key Detection Patterns**:
+- Tautological comparisons (always True/False)
+- Contradictory conditions in logic paths
+- Constant conditions using only constants
+- Type confusion between incompatible types
+- Undefined variable references
+- Unused variable declarations
+- Variable shadowing across scopes
+
+**Implementation**: See [Truthfulness Analysis](./trust5-framework/truthfulness-analysis.md) for detailed logic validation, data flow analysis, and Context7 integration patterns.
+
+### Relevance Analysis
+
+**Purpose**: Validates requirements fulfillment and purpose alignment
+
+**Key Detection Patterns**:
+- Missing requirement implementations
+- Unused functions and classes
+- Dead code (commented blocks, unreachable code)
+- Unresolved TODO/FIXME markers
+- Over-engineering beyond requirements
+- Feature creep detection
+
+**Implementation**: See [Relevance Analysis](./trust5-framework/relevance-analysis.md) for requirements traceability, dead code detection, and purpose alignment validation.
+
+### Usability Analysis
+
+**Purpose**: Assesses maintainability and understandability
+
+**Key Detection Patterns**:
+- High complexity (cyclomatic, cognitive)
+- Poor naming conventions
+- Long functions and deep nesting
+- Magic numbers without constants
+- Code duplication
+- Missing documentation
+- Poor separation of concerns
+
+**Metrics**:
+- Halstead complexity metrics
+- Maintainability Index (MI)
+- Coupling and cohesion measurements
+- Code organization assessment
+
+**Implementation**: See [Usability Analysis](./trust5-framework/usability-analysis.md) for advanced maintainability metrics, Halstead calculations, and code organization assessment.
+
+### Safety Analysis
+
+**Purpose**: Detects security vulnerabilities and validates error handling
+
+**Key Detection Patterns**:
+- SQL injection vulnerabilities
+- XSS vulnerabilities in web contexts
+- Resource leaks (files, connections)
+- Race conditions in concurrent code
+- Missing error handling
+- Weak cryptography usage
+- Hardcoded secrets and credentials
+
+**Security Coverage**:
+- OWASP Top 10 vulnerability patterns
+- Resource safety validation
+- Error handling best practices
+- Input validation completeness
+
+**Implementation**: See [Safety Analysis](./trust5-framework/safety-analysis.md) for advanced security analysis, resource leak detection, and Context7 OWASP integration.
+
+### Timeliness Analysis
+
+**Purpose**: Identifies performance optimization opportunities and modern practices
+
+**Key Detection Patterns**:
+- Inefficient data structure usage
+- Missing caching opportunities
+- Suboptimal algorithm choices
+- Unoptimized I/O operations
+- Deprecated API usage
+- Technology currency issues
+
+**Performance Optimization**:
+- Algorithmic efficiency checks
+- Caching opportunity detection
+- Data structure optimization
+- Async/await recommendations
+
+**Implementation**: See [Timeliness Analysis](./trust5-framework/timeliness-analysis.md) for performance optimization detection, caching opportunities, and technology currency checks.
+
+---
+
+## Advanced Scoring
+
+### Weighted Category Scoring
+
+TRUST 5 uses weighted scoring with category-specific weights:
+- Truthfulness: 25%
+- Relevance: 20%
+- Usability: 25%
+- Safety: 20%
+- Timeliness: 10%
+
+**Score Calculation Factors**:
+- Severity weighting (critical, high, medium, low)
+- Confidence scoring from detection algorithms
+- Impact factor based on code context
+- Complexity adjustment for file size/complexity
+- Trend factor based on historical data
+
+**Score Interpretation**:
+- 0.90-1.00: Excellent quality
+- 0.75-0.89: Good quality
+- 0.60-0.74: Acceptable quality
+- 0.40-0.59: Needs improvement
+- 0.00-0.39: Critical issues
+
+**Implementation**: See [Scoring Algorithms](./trust5-framework/scoring-algorithms.md) for comprehensive scoring methodology, factor calculations, and trend analysis.
+
+---
+
+## Best Practices
+
+1. **Pattern Customization**: Customize category-specific patterns for project context
+2. **Context7 Integration**: Leverage latest patterns from Context7 for accuracy
+3. **Weight Adjustment**: Adjust category weights based on project priorities
+4. **Trend Analysis**: Track score trends over time for improvement monitoring
+5. **Team Alignment**: Ensure category definitions align with team understanding
+6. **Regular Updates**: Update patterns regularly to reflect evolving best practices
+7. **CI/CD Integration**: Integrate with CI/CD for continuous quality monitoring
+8. **Education**: Educate team on TRUST 5 methodology for consistent application
+
+---
+
+## Related Modules
+
+- [TRUST 5 Validation](../trust5-validation.md): Core TRUST 5 implementation
+- [Security Analysis](../security-analysis.md): Safety category deep dive
+- [Quality Metrics](../quality-metrics.md): Usability category metrics
+- [Static Analysis](../static-analysis.md): Automated analysis tools
+
+---
+
+Version: 1.1.0 (Modularized)
+Last Updated: 2026-01-06
+Module: `modules/automated-code-review/trust5-framework.md`
+
+## Submodules
+
+- [Truthfulness Analysis](./trust5-framework/truthfulness-analysis.md): Logic correctness and data flow
+- [Relevance Analysis](./trust5-framework/relevance-analysis.md): Requirements traceability and dead code
+- [Usability Analysis](./trust5-framework/usability-analysis.md): Maintainability metrics and code organization
+- [Safety Analysis](./trust5-framework/safety-analysis.md): Security vulnerabilities and error handling
+- [Timeliness Analysis](./trust5-framework/timeliness-analysis.md): Performance optimization and modern practices
+- [Scoring Algorithms](./trust5-framework/scoring-algorithms.md): Weighted scoring and trend analysis