moai-adk 0.25.4__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

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

@@ -0,0 +1,263 @@
+# Automated Code Review with TRUST 5 Validation
+
+> Module: AI-powered automated code review with TRUST 5 validation framework and comprehensive quality analysis
+> Complexity: Advanced
+> Time: 35+ minutes
+> Dependencies: Python 3.8+, Context7 MCP, ast, pylint, flake8, bandit, mypy
+
+## Quick Reference
+
+### Core Capabilities
+
+The automated code review system provides comprehensive code quality analysis across multiple dimensions:
+
+TRUST 5 Framework:
+- Truthfulness: Code correctness and logic accuracy validation
+- Relevance: Requirements fulfillment and purpose alignment checking
+- Usability: Maintainability and understandability assessment
+- Safety: Security vulnerability and error handling detection
+- Timeliness: Performance standards and modern practices verification
+
+Static Analysis Integration:
+- pylint: Code quality and style checking
+- flake8: Style guide enforcement
+- bandit: Security vulnerability scanning
+- mypy: Type checking and validation
+
+Context7-Enhanced Analysis:
+- Up-to-date security patterns from OWASP and Semgrep
+- Performance anti-patterns from profiling best practices
+- Code quality patterns from SonarQube standards
+- TRUST 5 validation framework patterns
+
+### Key Components
+
+```python
+from moai_workflow_testing.automated_code_review import (
+    AutomatedCodeReviewer,
+    CodeReviewReport,
+    TrustCategory,
+    Severity,
+    IssueType
+)
+
+# Initialize automated code reviewer
+reviewer = AutomatedCodeReviewer(context7_client=context7)
+
+# Review entire codebase
+report = await reviewer.review_codebase(
+    project_path="/path/to/project",
+    include_patterns=["/*.py"],
+    exclude_patterns=["/tests/", "/__pycache__/"]
+)
+
+print(f"Overall TRUST Score: {report.overall_trust_score:.2f}")
+print(f"Files Reviewed: {report.summary_metrics['files_reviewed']}")
+print(f"Total Issues: {report.summary_metrics['total_issues']}")
+print(f"Critical Issues: {report.summary_metrics['critical_issues']}")
+```
+
+### TRUST 5 Scores
+
+The review system calculates scores for each TRUST category:
+
+```python
+for category, score in report.overall_category_scores.items():
+    print(f"{category.value}: {score:.2f}")
+```
+
+Category Score Calculation:
+- Scores range from 0.0 to 1.0
+- Penalties applied based on issue severity and confidence
+- Weighted average for overall score
+- Category weights: Truthfulness (25%), Relevance (20%), Usability (25%), Safety (20%), Timeliness (10%)
+
+### Issue Severity Levels
+
+Critical: Security vulnerabilities, syntax errors, data loss risks
+High: Complex logic issues, major performance problems, significant safety concerns
+Medium: Code smells, maintainability issues, moderate performance problems
+Low: Style violations, minor documentation issues, small optimizations
+Info: Suggestions and best practice recommendations
+
+---
+
+## Implementation Guide
+
+### Basic Code Review Workflow
+
+Step 1: Initialize the automated code reviewer with optional Context7 client for enhanced pattern detection
+
+Step 2: Review the codebase by specifying:
+- Project path to analyze
+- Include patterns for files to review (default: ["/*.py"])
+- Exclude patterns for directories to skip (default: ["/__pycache__/", "/venv/", "/tests/"])
+
+Step 3: Analyze the generated report which includes:
+- Overall TRUST score across all categories
+- Per-file review results with individual issues
+- Summary metrics with issue counts by severity and category
+- Critical issues requiring immediate attention
+- Actionable recommendations prioritized by impact
+
+### Single File Review
+
+For reviewing individual files:
+
+```python
+file_result = await reviewer.review_single_file("/path/to/file.py")
+print(f"File Trust Score: {file_result.trust_score:.2f}")
+print(f"Issues found: {len(file_result.issues)}")
+print(f"Lines of code: {file_result.lines_of_code}")
+```
+
+### Understanding Code Issues
+
+Each issue detected includes:
+
+```python
+for issue in file_result.issues:
+    print(f"Category: {issue.category.value}")
+    print(f"Severity: {issue.severity.value}")
+    print(f"Type: {issue.issue_type.value}")
+    print(f"Title: {issue.title}")
+    print(f"Description: {issue.description}")
+    print(f"Location: {issue.file_path}:{issue.line_number}")
+    print(f"Code snippet: {issue.code_snippet}")
+    print(f"Suggested fix: {issue.suggested_fix}")
+    print(f"Confidence: {issue.confidence:.2f}")
+    if issue.rule_violated:
+        print(f"Rule violated: {issue.rule_violated}")
+    if issue.external_reference:
+        print(f"Reference: {issue.external_reference}")
+```
+
+### Customizing Analysis Patterns
+
+Configure analysis patterns to match project standards:
+
+```python
+# Access analysis patterns
+patterns = await reviewer.context7_analyzer.load_analysis_patterns()
+
+# Customize quality thresholds
+patterns['quality']['long_functions']['max_lines'] = 100
+patterns['quality']['complex_conditionals']['max_complexity'] = 15
+patterns['quality']['deep_nesting']['max_depth'] = 5
+
+# Run review with custom patterns
+reviewer.analysis_patterns = patterns
+report = await reviewer.review_codebase(project_path)
+```
+
+---
+
+## Advanced Modules
+
+For detailed implementation and advanced features, see the specialized modules:
+
+### TRUST 5 Validation Framework
+
+See [trust5-validation.md](./trust5-validation.md) for:
+- Complete TRUST 5 category implementations
+- Custom validation rules and patterns
+- Category-specific analysis methods
+- Score calculation algorithms
+- Penalty and weight customization
+
+### Static Analysis Integration
+
+See [static-analysis.md](./static-analysis.md) for:
+- pylint, flake8, bandit, mypy integration details
+- Tool configuration and customization
+- Result parsing and normalization
+- Tool-to-TRUST category mapping
+- Error handling and fallback strategies
+
+### Security Analysis
+
+See [security-analysis.md](./security-analysis.md) for:
+- Context7-enhanced security pattern detection
+- OWASP Top 10 vulnerability scanning
+- SQL injection, command injection, path traversal detection
+- Security fix suggestions with references
+- Business logic vulnerability analysis
+
+### Quality Metrics
+
+See [quality-metrics.md](./quality-metrics.md) for:
+- Function length and complexity analysis
+- Nesting depth detection
+- Cyclomatic complexity calculation
+- Code metrics and statistics
+- Maintainability indices
+
+### Advanced TRUST 5 Framework
+
+See [automated-code-review/trust5-framework.md](./automated-code-review/trust5-framework.md) for:
+- Deep dive into TRUST 5 methodology
+- Category-specific analysis patterns
+- Advanced scoring algorithms
+- Custom rule creation
+- Integration with external validation tools
+
+### Context7 Integration
+
+See [automated-code-review/context7-integration.md](./automated-code-review/context7-integration.md) for:
+- Context7 MCP integration patterns
+- Real-time pattern loading
+- Security vulnerability databases
+- Performance optimization libraries
+- Code quality standards integration
+
+### Review Workflows
+
+See [automated-code-review/review-workflows.md](./automated-code-review/review-workflows.md) for:
+- CI/CD pipeline integration
+- Automated review workflows
+- Report generation and formatting
+- Team collaboration patterns
+- Continuous quality monitoring
+
+---
+
+## Best Practices
+
+1. Comprehensive Coverage: Analyze code across all TRUST 5 dimensions for complete quality assessment
+2. Context Integration: Leverage Context7 for up-to-date security and quality patterns
+3. Actionable Feedback: Provide specific, implementable suggestions with code examples
+4. Severity Prioritization: Focus on critical and high-severity issues first for maximum impact
+5. Continuous Integration: Integrate into CI/CD pipeline for automated reviews on every commit
+6. Custom Thresholds: Adjust analysis thresholds to match project standards and team preferences
+7. Regular Updates: Keep Context7 patterns current for latest vulnerability detection
+8. Team Consistency: Use consistent review rules across entire codebase for uniform quality
+
+---
+
+## Related Modules
+
+- [Smart Refactoring](./smart-refactoring.md): Automated refactoring with code quality improvements
+- [Performance Optimization](./performance-optimization.md): Performance profiling and bottleneck detection
+- [AI Debugging](./ai-debugging.md): AI-powered debugging and error resolution
+
+---
+
+## Module Structure
+
+```
+automated-code-review.md (this file)
+├── trust5-validation.md (TRUST 5 framework implementation)
+├── static-analysis.md (pylint, flake8, bandit, mypy integration)
+├── security-analysis.md (security vulnerability detection)
+├── quality-metrics.md (code quality, complexity, metrics)
+└── automated-code-review/
+    ├── trust5-framework.md (deep dive into TRUST 5 categories)
+    ├── context7-integration.md (Context7 MCP integration)
+    └── review-workflows.md (CI/CD and team workflows)
+```
+
+---
+
+Version: 2.0.0 (Modular Structure)
+Last Updated: 2026-01-06
+Module: `modules/automated-code-review.md`