aigroup-workflow 1.0.1 → 1.1.1

package/skills/jarvis/engineering-team/engineering/api-design-reviewer/scripts/api_scorecard.py

@@ -1,1661 +0,0 @@
-#!/usr/bin/env python3
-"""
-API Scorecard - Comprehensive API design quality assessment tool.
-
-This script evaluates API designs across multiple dimensions and generates
-a detailed scorecard with letter grades and improvement recommendations.
-
-Scoring Dimensions:
-- Consistency (30%): Naming conventions, response patterns, structural consistency
-- Documentation (20%): Completeness and clarity of API documentation  
-- Security (20%): Authentication, authorization, and security best practices
-- Usability (15%): Ease of use, discoverability, and developer experience
-- Performance (15%): Caching, pagination, and efficiency patterns
-
-Generates letter grades (A-F) with detailed breakdowns and actionable recommendations.
-"""
-
-import argparse
-import json
-import re
-import sys
-from typing import Any, Dict, List, Optional, Set, Tuple
-from dataclasses import dataclass, field
-from enum import Enum
-import math
-
-
-class ScoreCategory(Enum):
-    """Scoring categories."""
-    CONSISTENCY = "consistency"
-    DOCUMENTATION = "documentation"
-    SECURITY = "security"
-    USABILITY = "usability"
-    PERFORMANCE = "performance"
-
-
-@dataclass
-class CategoryScore:
-    """Score for a specific category."""
-    category: ScoreCategory
-    score: float  # 0-100
-    max_score: float  # Usually 100
-    weight: float  # Percentage weight in overall score
-    issues: List[str] = field(default_factory=list)
-    recommendations: List[str] = field(default_factory=list)
-    
-    @property
-    def letter_grade(self) -> str:
-        """Convert score to letter grade."""
-        if self.score >= 90:
-            return "A"
-        elif self.score >= 80:
-            return "B"
-        elif self.score >= 70:
-            return "C"
-        elif self.score >= 60:
-            return "D"
-        else:
-            return "F"
-    
-    @property
-    def weighted_score(self) -> float:
-        """Calculate weighted contribution to overall score."""
-        return (self.score / 100.0) * self.weight
-
-
-@dataclass
-class APIScorecard:
-    """Complete API scorecard with all category scores."""
-    category_scores: Dict[ScoreCategory, CategoryScore] = field(default_factory=dict)
-    overall_score: float = 0.0
-    overall_grade: str = "F"
-    total_endpoints: int = 0
-    api_info: Dict[str, Any] = field(default_factory=dict)
-    
-    def calculate_overall_score(self) -> None:
-        """Calculate overall weighted score and grade."""
-        self.overall_score = sum(score.weighted_score for score in self.category_scores.values())
-        
-        if self.overall_score >= 90:
-            self.overall_grade = "A"
-        elif self.overall_score >= 80:
-            self.overall_grade = "B"
-        elif self.overall_score >= 70:
-            self.overall_grade = "C"
-        elif self.overall_score >= 60:
-            self.overall_grade = "D"
-        else:
-            self.overall_grade = "F"
-    
-    def get_top_recommendations(self, limit: int = 5) -> List[str]:
-        """Get top recommendations across all categories."""
-        all_recommendations = []
-        for category_score in self.category_scores.values():
-            for rec in category_score.recommendations:
-                all_recommendations.append(f"{category_score.category.value.title()}: {rec}")
-        
-        # Sort by category weight (highest impact first)
-        weighted_recs = []
-        for category_score in sorted(self.category_scores.values(), 
-                                   key=lambda x: x.weight, reverse=True):
-            for rec in category_score.recommendations[:2]:  # Top 2 per category
-                weighted_recs.append(f"{category_score.category.value.title()}: {rec}")
-        
-        return weighted_recs[:limit]
-
-
-class APIScoringEngine:
-    """Main API scoring engine."""
-    
-    def __init__(self):
-        self.scorecard = APIScorecard()
-        self.spec: Optional[Dict] = None
-        
-        # Regex patterns for validation
-        self.kebab_case_pattern = re.compile(r'^[a-z]+(?:-[a-z0-9]+)*$')
-        self.camel_case_pattern = re.compile(r'^[a-z][a-zA-Z0-9]*$')
-        self.pascal_case_pattern = re.compile(r'^[A-Z][a-zA-Z0-9]*$')
-        
-        # HTTP methods
-        self.http_methods = {'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'}
-        
-        # Category weights (must sum to 100)
-        self.category_weights = {
-            ScoreCategory.CONSISTENCY: 30.0,
-            ScoreCategory.DOCUMENTATION: 20.0,
-            ScoreCategory.SECURITY: 20.0,
-            ScoreCategory.USABILITY: 15.0,
-            ScoreCategory.PERFORMANCE: 15.0
-        }
-    
-    def score_api(self, spec: Dict[str, Any]) -> APIScorecard:
-        """Generate comprehensive API scorecard."""
-        self.spec = spec
-        self.scorecard = APIScorecard()
-        
-        # Extract basic API info
-        self._extract_api_info()
-        
-        # Score each category
-        self._score_consistency()
-        self._score_documentation()
-        self._score_security()
-        self._score_usability()
-        self._score_performance()
-        
-        # Calculate overall score
-        self.scorecard.calculate_overall_score()
-        
-        return self.scorecard
-    
-    def _extract_api_info(self) -> None:
-        """Extract basic API information."""
-        info = self.spec.get('info', {})
-        paths = self.spec.get('paths', {})
-        
-        self.scorecard.api_info = {
-            'title': info.get('title', 'Unknown API'),
-            'version': info.get('version', ''),
-            'description': info.get('description', ''),
-            'total_paths': len(paths),
-            'openapi_version': self.spec.get('openapi', self.spec.get('swagger', ''))
-        }
-        
-        # Count total endpoints
-        endpoint_count = 0
-        for path_obj in paths.values():
-            if isinstance(path_obj, dict):
-                endpoint_count += len([m for m in path_obj.keys() 
-                                     if m.upper() in self.http_methods])
-        
-        self.scorecard.total_endpoints = endpoint_count
-    
-    def _score_consistency(self) -> None:
-        """Score API consistency (30% weight)."""
-        category = ScoreCategory.CONSISTENCY
-        score = CategoryScore(
-            category=category,
-            score=0.0,
-            max_score=100.0,
-            weight=self.category_weights[category]
-        )
-        
-        consistency_checks = [
-            self._check_naming_consistency(),
-            self._check_response_consistency(),
-            self._check_error_format_consistency(),
-            self._check_parameter_consistency(),
-            self._check_url_structure_consistency(),
-            self._check_http_method_consistency(),
-            self._check_status_code_consistency()
-        ]
-        
-        # Average the consistency scores
-        valid_scores = [s for s in consistency_checks if s is not None]
-        if valid_scores:
-            score.score = sum(valid_scores) / len(valid_scores)
-        
-        # Add specific recommendations based on low scores
-        if score.score < 70:
-            score.recommendations.extend([
-                "Review naming conventions across all endpoints and schemas",
-                "Standardize response formats and error structures",
-                "Ensure consistent HTTP method usage patterns"
-            ])
-        elif score.score < 85:
-            score.recommendations.extend([
-                "Minor consistency improvements needed in naming or response formats",
-                "Consider creating API design guidelines document"
-            ])
-        
-        self.scorecard.category_scores[category] = score
-    
-    def _check_naming_consistency(self) -> float:
-        """Check naming convention consistency."""
-        paths = self.spec.get('paths', {})
-        schemas = self.spec.get('components', {}).get('schemas', {})
-        
-        total_checks = 0
-        passed_checks = 0
-        
-        # Check path naming (should be kebab-case)
-        for path in paths.keys():
-            segments = [seg for seg in path.split('/') if seg and not seg.startswith('{')]
-            for segment in segments:
-                total_checks += 1
-                if self.kebab_case_pattern.match(segment) or re.match(r'^v\d+$', segment):
-                    passed_checks += 1
-        
-        # Check schema naming (should be PascalCase)
-        for schema_name in schemas.keys():
-            total_checks += 1
-            if self.pascal_case_pattern.match(schema_name):
-                passed_checks += 1
-        
-        # Check property naming within schemas
-        for schema in schemas.values():
-            if isinstance(schema, dict) and 'properties' in schema:
-                for prop_name in schema['properties'].keys():
-                    total_checks += 1
-                    if self.camel_case_pattern.match(prop_name):
-                        passed_checks += 1
-        
-        return (passed_checks / total_checks * 100) if total_checks > 0 else 100
-    
-    def _check_response_consistency(self) -> float:
-        """Check response format consistency."""
-        paths = self.spec.get('paths', {})
-        
-        response_patterns = []
-        total_responses = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods or not isinstance(operation, dict):
-                    continue
-                
-                responses = operation.get('responses', {})
-                for status_code, response in responses.items():
-                    if not isinstance(response, dict):
-                        continue
-                        
-                    total_responses += 1
-                    content = response.get('content', {})
-                    
-                    # Analyze response structure
-                    for media_type, media_obj in content.items():
-                        schema = media_obj.get('schema', {})
-                        pattern = self._extract_schema_pattern(schema)
-                        response_patterns.append(pattern)
-        
-        # Calculate consistency by comparing patterns
-        if not response_patterns:
-            return 100
-        
-        pattern_counts = {}
-        for pattern in response_patterns:
-            pattern_key = json.dumps(pattern, sort_keys=True)
-            pattern_counts[pattern_key] = pattern_counts.get(pattern_key, 0) + 1
-        
-        # Most common pattern should dominate for good consistency
-        max_count = max(pattern_counts.values()) if pattern_counts else 0
-        consistency_ratio = max_count / len(response_patterns) if response_patterns else 1
-        
-        return consistency_ratio * 100
-    
-    def _extract_schema_pattern(self, schema: Dict[str, Any]) -> Dict[str, Any]:
-        """Extract a pattern from a schema for consistency checking."""
-        if not isinstance(schema, dict):
-            return {}
-        
-        pattern = {
-            'type': schema.get('type'),
-            'has_properties': 'properties' in schema,
-            'has_items': 'items' in schema,
-            'required_count': len(schema.get('required', [])),
-            'property_count': len(schema.get('properties', {}))
-        }
-        
-        return pattern
-    
-    def _check_error_format_consistency(self) -> float:
-        """Check error response format consistency."""
-        paths = self.spec.get('paths', {})
-        error_responses = []
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                responses = operation.get('responses', {})
-                for status_code, response in responses.items():
-                    try:
-                        code_int = int(status_code)
-                        if code_int >= 400:  # Error responses
-                            content = response.get('content', {})
-                            for media_type, media_obj in content.items():
-                                schema = media_obj.get('schema', {})
-                                error_responses.append(self._extract_schema_pattern(schema))
-                    except ValueError:
-                        continue
-        
-        if not error_responses:
-            return 80  # No error responses defined - somewhat concerning
-        
-        # Check consistency of error response formats
-        pattern_counts = {}
-        for pattern in error_responses:
-            pattern_key = json.dumps(pattern, sort_keys=True)
-            pattern_counts[pattern_key] = pattern_counts.get(pattern_key, 0) + 1
-        
-        max_count = max(pattern_counts.values()) if pattern_counts else 0
-        consistency_ratio = max_count / len(error_responses) if error_responses else 1
-        
-        return consistency_ratio * 100
-    
-    def _check_parameter_consistency(self) -> float:
-        """Check parameter naming and usage consistency."""
-        paths = self.spec.get('paths', {})
-        
-        query_params = []
-        path_params = []
-        header_params = []
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                parameters = operation.get('parameters', [])
-                for param in parameters:
-                    if not isinstance(param, dict):
-                        continue
-                        
-                    param_name = param.get('name', '')
-                    param_in = param.get('in', '')
-                    
-                    if param_in == 'query':
-                        query_params.append(param_name)
-                    elif param_in == 'path':
-                        path_params.append(param_name)
-                    elif param_in == 'header':
-                        header_params.append(param_name)
-        
-        # Check naming consistency for each parameter type
-        scores = []
-        
-        # Query parameters should be camelCase or kebab-case
-        if query_params:
-            valid_query = sum(1 for p in query_params 
-                            if self.camel_case_pattern.match(p) or self.kebab_case_pattern.match(p))
-            scores.append((valid_query / len(query_params)) * 100)
-        
-        # Path parameters should be camelCase or kebab-case
-        if path_params:
-            valid_path = sum(1 for p in path_params 
-                           if self.camel_case_pattern.match(p) or self.kebab_case_pattern.match(p))
-            scores.append((valid_path / len(path_params)) * 100)
-        
-        return sum(scores) / len(scores) if scores else 100
-    
-    def _check_url_structure_consistency(self) -> float:
-        """Check URL structure and pattern consistency."""
-        paths = self.spec.get('paths', {})
-        
-        total_paths = len(paths)
-        if total_paths == 0:
-            return 0
-        
-        structure_score = 0
-        
-        # Check for consistent versioning
-        versioned_paths = 0
-        for path in paths.keys():
-            if re.search(r'/v\d+/', path):
-                versioned_paths += 1
-        
-        # Either all or none should be versioned for consistency
-        if versioned_paths == 0 or versioned_paths == total_paths:
-            structure_score += 25
-        elif versioned_paths > total_paths * 0.8:
-            structure_score += 20
-        
-        # Check for reasonable path depth
-        reasonable_depth = 0
-        for path in paths.keys():
-            segments = [seg for seg in path.split('/') if seg]
-            if 2 <= len(segments) <= 5:  # Reasonable depth
-                reasonable_depth += 1
-        
-        structure_score += (reasonable_depth / total_paths) * 25
-        
-        # Check for RESTful resource patterns
-        restful_patterns = 0
-        for path in paths.keys():
-            # Look for patterns like /resources/{id} or /resources
-            if re.match(r'^/[a-z-]+(/\{[^}]+\})?(/[a-z-]+)*$', path):
-                restful_patterns += 1
-        
-        structure_score += (restful_patterns / total_paths) * 30
-        
-        # Check for consistent trailing slash usage
-        with_slash = sum(1 for path in paths.keys() if path.endswith('/'))
-        without_slash = total_paths - with_slash
-        
-        # Either all or none should have trailing slashes
-        if with_slash == 0 or without_slash == 0:
-            structure_score += 20
-        elif min(with_slash, without_slash) < total_paths * 0.1:
-            structure_score += 15
-        
-        return min(structure_score, 100)
-    
-    def _check_http_method_consistency(self) -> float:
-        """Check HTTP method usage consistency."""
-        paths = self.spec.get('paths', {})
-        
-        method_usage = {}
-        total_operations = 0
-        
-        for path, path_obj in paths.items():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method in path_obj.keys():
-                if method.upper() in self.http_methods:
-                    method_upper = method.upper()
-                    total_operations += 1
-                    
-                    # Analyze method usage patterns
-                    if method_upper not in method_usage:
-                        method_usage[method_upper] = {'count': 0, 'appropriate': 0}
-                    
-                    method_usage[method_upper]['count'] += 1
-                    
-                    # Check if method usage seems appropriate
-                    if self._is_method_usage_appropriate(path, method_upper, path_obj[method]):
-                        method_usage[method_upper]['appropriate'] += 1
-        
-        if total_operations == 0:
-            return 0
-        
-        # Calculate appropriateness score
-        total_appropriate = sum(data['appropriate'] for data in method_usage.values())
-        return (total_appropriate / total_operations) * 100
-    
-    def _is_method_usage_appropriate(self, path: str, method: str, operation: Dict) -> bool:
-        """Check if HTTP method usage is appropriate for the endpoint."""
-        # Simple heuristics for method appropriateness
-        has_request_body = 'requestBody' in operation
-        path_has_id = '{' in path and '}' in path
-        
-        if method == 'GET':
-            return not has_request_body  # GET should not have body
-        elif method == 'POST':
-            return not path_has_id  # POST typically for collections
-        elif method == 'PUT':
-            return path_has_id and has_request_body  # PUT for specific resources
-        elif method == 'PATCH':
-            return path_has_id  # PATCH for specific resources
-        elif method == 'DELETE':
-            return path_has_id  # DELETE for specific resources
-        
-        return True  # Default to appropriate for other methods
-    
-    def _check_status_code_consistency(self) -> float:
-        """Check HTTP status code usage consistency."""
-        paths = self.spec.get('paths', {})
-        
-        method_status_patterns = {}
-        total_operations = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                total_operations += 1
-                responses = operation.get('responses', {})
-                status_codes = set(responses.keys())
-                
-                if method.upper() not in method_status_patterns:
-                    method_status_patterns[method.upper()] = []
-                
-                method_status_patterns[method.upper()].append(status_codes)
-        
-        if total_operations == 0:
-            return 0
-        
-        # Check consistency within each method type
-        consistency_scores = []
-        
-        for method, status_patterns in method_status_patterns.items():
-            if not status_patterns:
-                continue
-            
-            # Find common status codes for this method
-            all_codes = set()
-            for pattern in status_patterns:
-                all_codes.update(pattern)
-            
-            # Calculate how many operations use the most common codes
-            code_usage = {}
-            for code in all_codes:
-                code_usage[code] = sum(1 for pattern in status_patterns if code in pattern)
-            
-            # Score based on consistency of common status codes
-            if status_patterns:
-                avg_consistency = sum(
-                    len([code for code in pattern if code_usage.get(code, 0) > len(status_patterns) * 0.5]) 
-                    for pattern in status_patterns
-                ) / len(status_patterns)
-                
-                method_consistency = min(avg_consistency / 3.0 * 100, 100)  # Expect ~3 common codes
-                consistency_scores.append(method_consistency)
-        
-        return sum(consistency_scores) / len(consistency_scores) if consistency_scores else 100
-    
-    def _score_documentation(self) -> None:
-        """Score API documentation quality (20% weight)."""
-        category = ScoreCategory.DOCUMENTATION
-        score = CategoryScore(
-            category=category,
-            score=0.0,
-            max_score=100.0,
-            weight=self.category_weights[category]
-        )
-        
-        documentation_checks = [
-            self._check_api_level_documentation(),
-            self._check_endpoint_documentation(),
-            self._check_schema_documentation(),
-            self._check_parameter_documentation(),
-            self._check_response_documentation(),
-            self._check_example_coverage()
-        ]
-        
-        valid_scores = [s for s in documentation_checks if s is not None]
-        if valid_scores:
-            score.score = sum(valid_scores) / len(valid_scores)
-        
-        # Add recommendations based on score
-        if score.score < 60:
-            score.recommendations.extend([
-                "Add comprehensive descriptions to all API components",
-                "Include examples for complex operations and schemas",
-                "Document all parameters and response fields"
-            ])
-        elif score.score < 80:
-            score.recommendations.extend([
-                "Improve documentation completeness for some endpoints",
-                "Add more examples to enhance developer experience"
-            ])
-        
-        self.scorecard.category_scores[category] = score
-    
-    def _check_api_level_documentation(self) -> float:
-        """Check API-level documentation completeness."""
-        info = self.spec.get('info', {})
-        score = 0
-        
-        # Required fields
-        if info.get('title'):
-            score += 20
-        if info.get('version'):
-            score += 20
-        if info.get('description') and len(info['description']) > 20:
-            score += 30
-        
-        # Optional but recommended fields
-        if info.get('contact'):
-            score += 15
-        if info.get('license'):
-            score += 15
-        
-        return score
-    
-    def _check_endpoint_documentation(self) -> float:
-        """Check endpoint-level documentation completeness."""
-        paths = self.spec.get('paths', {})
-        
-        total_operations = 0
-        documented_operations = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                total_operations += 1
-                doc_score = 0
-                
-                if operation.get('summary'):
-                    doc_score += 1
-                if operation.get('description') and len(operation['description']) > 20:
-                    doc_score += 1
-                if operation.get('operationId'):
-                    doc_score += 1
-                
-                # Consider it documented if it has at least 2/3 elements
-                if doc_score >= 2:
-                    documented_operations += 1
-        
-        return (documented_operations / total_operations * 100) if total_operations > 0 else 100
-    
-    def _check_schema_documentation(self) -> float:
-        """Check schema documentation completeness."""
-        schemas = self.spec.get('components', {}).get('schemas', {})
-        
-        if not schemas:
-            return 80  # No schemas to document
-        
-        total_schemas = len(schemas)
-        documented_schemas = 0
-        
-        for schema_name, schema in schemas.items():
-            if not isinstance(schema, dict):
-                continue
-            
-            doc_elements = 0
-            
-            # Schema-level description
-            if schema.get('description'):
-                doc_elements += 1
-            
-            # Property descriptions
-            properties = schema.get('properties', {})
-            if properties:
-                described_props = sum(1 for prop in properties.values() 
-                                    if isinstance(prop, dict) and prop.get('description'))
-                if described_props > len(properties) * 0.5:  # At least 50% documented
-                    doc_elements += 1
-            
-            # Examples
-            if schema.get('example') or any(
-                isinstance(prop, dict) and prop.get('example') 
-                for prop in properties.values()
-            ):
-                doc_elements += 1
-            
-            if doc_elements >= 2:
-                documented_schemas += 1
-        
-        return (documented_schemas / total_schemas * 100) if total_schemas > 0 else 100
-    
-    def _check_parameter_documentation(self) -> float:
-        """Check parameter documentation completeness."""
-        paths = self.spec.get('paths', {})
-        
-        total_params = 0
-        documented_params = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                parameters = operation.get('parameters', [])
-                for param in parameters:
-                    if not isinstance(param, dict):
-                        continue
-                    
-                    total_params += 1
-                    
-                    doc_score = 0
-                    if param.get('description'):
-                        doc_score += 1
-                    if param.get('example') or (param.get('schema', {}).get('example')):
-                        doc_score += 1
-                    
-                    if doc_score >= 1:  # At least description
-                        documented_params += 1
-        
-        return (documented_params / total_params * 100) if total_params > 0 else 100
-    
-    def _check_response_documentation(self) -> float:
-        """Check response documentation completeness."""
-        paths = self.spec.get('paths', {})
-        
-        total_responses = 0
-        documented_responses = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                responses = operation.get('responses', {})
-                for status_code, response in responses.items():
-                    if not isinstance(response, dict):
-                        continue
-                    
-                    total_responses += 1
-                    
-                    if response.get('description'):
-                        documented_responses += 1
-        
-        return (documented_responses / total_responses * 100) if total_responses > 0 else 100
-    
-    def _check_example_coverage(self) -> float:
-        """Check example coverage across the API."""
-        paths = self.spec.get('paths', {})
-        schemas = self.spec.get('components', {}).get('schemas', {})
-        
-        # Check examples in operations
-        total_operations = 0
-        operations_with_examples = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                total_operations += 1
-                
-                has_example = False
-                
-                # Check request body examples
-                request_body = operation.get('requestBody', {})
-                if self._has_examples(request_body.get('content', {})):
-                    has_example = True
-                
-                # Check response examples
-                responses = operation.get('responses', {})
-                for response in responses.values():
-                    if isinstance(response, dict) and self._has_examples(response.get('content', {})):
-                        has_example = True
-                        break
-                
-                if has_example:
-                    operations_with_examples += 1
-        
-        # Check examples in schemas
-        total_schemas = len(schemas)
-        schemas_with_examples = 0
-        
-        for schema in schemas.values():
-            if isinstance(schema, dict) and self._schema_has_examples(schema):
-                schemas_with_examples += 1
-        
-        # Combine scores
-        operation_score = (operations_with_examples / total_operations * 100) if total_operations > 0 else 100
-        schema_score = (schemas_with_examples / total_schemas * 100) if total_schemas > 0 else 100
-        
-        return (operation_score + schema_score) / 2
-    
-    def _has_examples(self, content: Dict[str, Any]) -> bool:
-        """Check if content has examples."""
-        for media_type, media_obj in content.items():
-            if isinstance(media_obj, dict):
-                if media_obj.get('example') or media_obj.get('examples'):
-                    return True
-        return False
-    
-    def _schema_has_examples(self, schema: Dict[str, Any]) -> bool:
-        """Check if schema has examples."""
-        if schema.get('example'):
-            return True
-        
-        properties = schema.get('properties', {})
-        for prop in properties.values():
-            if isinstance(prop, dict) and prop.get('example'):
-                return True
-        
-        return False
-    
-    def _score_security(self) -> None:
-        """Score API security implementation (20% weight)."""
-        category = ScoreCategory.SECURITY
-        score = CategoryScore(
-            category=category,
-            score=0.0,
-            max_score=100.0,
-            weight=self.category_weights[category]
-        )
-        
-        security_checks = [
-            self._check_security_schemes(),
-            self._check_security_requirements(),
-            self._check_https_usage(),
-            self._check_authentication_patterns(),
-            self._check_sensitive_data_handling()
-        ]
-        
-        valid_scores = [s for s in security_checks if s is not None]
-        if valid_scores:
-            score.score = sum(valid_scores) / len(valid_scores)
-        
-        # Add recommendations
-        if score.score < 50:
-            score.recommendations.extend([
-                "Implement comprehensive security schemes (OAuth2, API keys, etc.)",
-                "Ensure all endpoints have appropriate security requirements",
-                "Add input validation and rate limiting patterns"
-            ])
-        elif score.score < 80:
-            score.recommendations.extend([
-                "Review security coverage for all endpoints",
-                "Consider additional security measures for sensitive operations"
-            ])
-        
-        self.scorecard.category_scores[category] = score
-    
-    def _check_security_schemes(self) -> float:
-        """Check security scheme definitions."""
-        security_schemes = self.spec.get('components', {}).get('securitySchemes', {})
-        
-        if not security_schemes:
-            return 20  # Very low score for no security
-        
-        score = 40  # Base score for having security schemes
-        
-        scheme_types = set()
-        for scheme in security_schemes.values():
-            if isinstance(scheme, dict):
-                scheme_type = scheme.get('type')
-                scheme_types.add(scheme_type)
-        
-        # Bonus for modern security schemes
-        if 'oauth2' in scheme_types:
-            score += 30
-        if 'apiKey' in scheme_types:
-            score += 15
-        if 'http' in scheme_types:
-            score += 15
-        
-        return min(score, 100)
-    
-    def _check_security_requirements(self) -> float:
-        """Check security requirement coverage."""
-        paths = self.spec.get('paths', {})
-        global_security = self.spec.get('security', [])
-        
-        total_operations = 0
-        secured_operations = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                total_operations += 1
-                
-                # Check if operation has security requirements
-                operation_security = operation.get('security')
-                
-                if operation_security is not None:
-                    secured_operations += 1
-                elif global_security:
-                    secured_operations += 1
-        
-        return (secured_operations / total_operations * 100) if total_operations > 0 else 0
-    
-    def _check_https_usage(self) -> float:
-        """Check HTTPS enforcement."""
-        servers = self.spec.get('servers', [])
-        
-        if not servers:
-            return 60  # No servers defined - assume HTTPS
-        
-        https_servers = 0
-        for server in servers:
-            if isinstance(server, dict):
-                url = server.get('url', '')
-                if url.startswith('https://') or not url.startswith('http://'):
-                    https_servers += 1
-        
-        return (https_servers / len(servers) * 100) if servers else 100
-    
-    def _check_authentication_patterns(self) -> float:
-        """Check authentication pattern quality."""
-        security_schemes = self.spec.get('components', {}).get('securitySchemes', {})
-        
-        if not security_schemes:
-            return 0
-        
-        pattern_scores = []
-        
-        for scheme in security_schemes.values():
-            if not isinstance(scheme, dict):
-                continue
-            
-            scheme_type = scheme.get('type', '').lower()
-            
-            if scheme_type == 'oauth2':
-                # OAuth2 is highly recommended
-                flows = scheme.get('flows', {})
-                if flows:
-                    pattern_scores.append(95)
-                else:
-                    pattern_scores.append(80)
-            elif scheme_type == 'http':
-                scheme_scheme = scheme.get('scheme', '').lower()
-                if scheme_scheme == 'bearer':
-                    pattern_scores.append(85)
-                elif scheme_scheme == 'basic':
-                    pattern_scores.append(60)  # Less secure
-                else:
-                    pattern_scores.append(70)
-            elif scheme_type == 'apikey':
-                location = scheme.get('in', '').lower()
-                if location == 'header':
-                    pattern_scores.append(75)
-                else:
-                    pattern_scores.append(60)  # Query/cookie less secure
-            else:
-                pattern_scores.append(50)  # Unknown scheme
-        
-        return sum(pattern_scores) / len(pattern_scores) if pattern_scores else 0
-    
-    def _check_sensitive_data_handling(self) -> float:
-        """Check sensitive data handling patterns."""
-        # This is a simplified check - in reality would need more sophisticated analysis
-        schemas = self.spec.get('components', {}).get('schemas', {})
-        
-        score = 80  # Default good score
-        
-        # Look for potential sensitive fields without proper handling
-        sensitive_field_names = {'password', 'secret', 'token', 'key', 'ssn', 'credit_card'}
-        
-        for schema in schemas.values():
-            if not isinstance(schema, dict):
-                continue
-            
-            properties = schema.get('properties', {})
-            for prop_name, prop_def in properties.items():
-                if not isinstance(prop_def, dict):
-                    continue
-                
-                # Check for sensitive field names
-                if any(sensitive in prop_name.lower() for sensitive in sensitive_field_names):
-                    # Check if it's marked as sensitive (writeOnly, format: password, etc.)
-                    if not (prop_def.get('writeOnly') or 
-                           prop_def.get('format') == 'password' or
-                           'password' in prop_def.get('description', '').lower()):
-                        score -= 10  # Penalty for exposed sensitive field
-        
-        return max(score, 0)
-    
-    def _score_usability(self) -> None:
-        """Score API usability and developer experience (15% weight)."""
-        category = ScoreCategory.USABILITY
-        score = CategoryScore(
-            category=category,
-            score=0.0,
-            max_score=100.0,
-            weight=self.category_weights[category]
-        )
-        
-        usability_checks = [
-            self._check_discoverability(),
-            self._check_error_handling(),
-            self._check_filtering_and_searching(),
-            self._check_resource_relationships(),
-            self._check_developer_experience()
-        ]
-        
-        valid_scores = [s for s in usability_checks if s is not None]
-        if valid_scores:
-            score.score = sum(valid_scores) / len(valid_scores)
-        
-        # Add recommendations
-        if score.score < 60:
-            score.recommendations.extend([
-                "Improve error messages with actionable guidance",
-                "Add filtering and search capabilities to list endpoints",
-                "Enhance resource discoverability with better linking"
-            ])
-        elif score.score < 80:
-            score.recommendations.extend([
-                "Consider adding HATEOAS links for better discoverability",
-                "Enhance developer experience with better examples"
-            ])
-        
-        self.scorecard.category_scores[category] = score
-    
-    def _check_discoverability(self) -> float:
-        """Check API discoverability features."""
-        paths = self.spec.get('paths', {})
-        
-        # Look for root/discovery endpoints
-        has_root = '/' in paths or any(path == '/api' or path.startswith('/api/') for path in paths)
-        
-        # Look for HATEOAS patterns in responses
-        hateoas_score = 0
-        total_responses = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                responses = operation.get('responses', {})
-                for response in responses.values():
-                    if not isinstance(response, dict):
-                        continue
-                    
-                    total_responses += 1
-                    
-                    # Look for link-like properties in response schemas
-                    content = response.get('content', {})
-                    for media_obj in content.values():
-                        schema = media_obj.get('schema', {})
-                        if self._has_link_properties(schema):
-                            hateoas_score += 1
-                            break
-        
-        discovery_score = 50 if has_root else 30
-        if total_responses > 0:
-            hateoas_ratio = hateoas_score / total_responses
-            discovery_score += hateoas_ratio * 50
-        
-        return min(discovery_score, 100)
-    
-    def _has_link_properties(self, schema: Dict[str, Any]) -> bool:
-        """Check if schema has link-like properties."""
-        if not isinstance(schema, dict):
-            return False
-        
-        properties = schema.get('properties', {})
-        link_indicators = {'links', '_links', 'href', 'url', 'self', 'next', 'prev'}
-        
-        return any(prop_name.lower() in link_indicators for prop_name in properties.keys())
-    
-    def _check_error_handling(self) -> float:
-        """Check error handling quality."""
-        paths = self.spec.get('paths', {})
-        
-        total_operations = 0
-        operations_with_errors = 0
-        detailed_error_responses = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                total_operations += 1
-                responses = operation.get('responses', {})
-                
-                # Check for error responses
-                has_error_responses = any(
-                    status_code.startswith('4') or status_code.startswith('5')
-                    for status_code in responses.keys()
-                )
-                
-                if has_error_responses:
-                    operations_with_errors += 1
-                    
-                    # Check for detailed error schemas
-                    for status_code, response in responses.items():
-                        if (status_code.startswith('4') or status_code.startswith('5')) and isinstance(response, dict):
-                            content = response.get('content', {})
-                            for media_obj in content.values():
-                                schema = media_obj.get('schema', {})
-                                if self._has_detailed_error_schema(schema):
-                                    detailed_error_responses += 1
-                                    break
-                            break
-        
-        if total_operations == 0:
-            return 0
-        
-        error_coverage = (operations_with_errors / total_operations) * 60
-        error_detail = (detailed_error_responses / operations_with_errors * 40) if operations_with_errors > 0 else 0
-        
-        return error_coverage + error_detail
-    
-    def _has_detailed_error_schema(self, schema: Dict[str, Any]) -> bool:
-        """Check if error schema has detailed information."""
-        if not isinstance(schema, dict):
-            return False
-        
-        properties = schema.get('properties', {})
-        error_fields = {'error', 'message', 'details', 'code', 'timestamp'}
-        
-        matching_fields = sum(1 for field in error_fields if field in properties)
-        return matching_fields >= 2  # At least 2 standard error fields
-    
-    def _check_filtering_and_searching(self) -> float:
-        """Check filtering and search capabilities."""
-        paths = self.spec.get('paths', {})
-        
-        collection_endpoints = 0
-        endpoints_with_filtering = 0
-        
-        for path, path_obj in paths.items():
-            if not isinstance(path_obj, dict):
-                continue
-            
-            # Identify collection endpoints (no path parameters)
-            if '{' not in path:
-                get_operation = path_obj.get('get')
-                if get_operation:
-                    collection_endpoints += 1
-                    
-                    # Check for filtering/search parameters
-                    parameters = get_operation.get('parameters', [])
-                    filter_params = {'filter', 'search', 'q', 'query', 'limit', 'page', 'offset'}
-                    
-                    has_filtering = any(
-                        isinstance(param, dict) and param.get('name', '').lower() in filter_params
-                        for param in parameters
-                    )
-                    
-                    if has_filtering:
-                        endpoints_with_filtering += 1
-        
-        return (endpoints_with_filtering / collection_endpoints * 100) if collection_endpoints > 0 else 100
-    
-    def _check_resource_relationships(self) -> float:
-        """Check resource relationship handling."""
-        paths = self.spec.get('paths', {})
-        schemas = self.spec.get('components', {}).get('schemas', {})
-        
-        # Look for nested resource patterns
-        nested_resources = 0
-        total_resource_paths = 0
-        
-        for path in paths.keys():
-            # Skip root paths
-            if path.count('/') >= 3:  # e.g., /api/users/123/orders
-                total_resource_paths += 1
-                if '{' in path:
-                    nested_resources += 1
-        
-        # Look for relationship fields in schemas
-        schemas_with_relations = 0
-        for schema in schemas.values():
-            if not isinstance(schema, dict):
-                continue
-            
-            properties = schema.get('properties', {})
-            relation_indicators = {'id', '_id', 'ref', 'link', 'relationship'}
-            
-            has_relations = any(
-                any(indicator in prop_name.lower() for indicator in relation_indicators)
-                for prop_name in properties.keys()
-            )
-            
-            if has_relations:
-                schemas_with_relations += 1
-        
-        nested_score = (nested_resources / total_resource_paths * 50) if total_resource_paths > 0 else 25
-        schema_score = (schemas_with_relations / len(schemas) * 50) if schemas else 25
-        
-        return nested_score + schema_score
-    
-    def _check_developer_experience(self) -> float:
-        """Check overall developer experience factors."""
-        # This is a composite score based on various DX factors
-        factors = []
-        
-        # Factor 1: Consistent response structure
-        factors.append(self._check_response_consistency())
-        
-        # Factor 2: Clear operation IDs
-        paths = self.spec.get('paths', {})
-        total_operations = 0
-        operations_with_ids = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-                
-            for method, operation in path_obj.items():
-                if method.upper() not in self.http_methods:
-                    continue
-                
-                total_operations += 1
-                if isinstance(operation, dict) and operation.get('operationId'):
-                    operations_with_ids += 1
-        
-        operation_id_score = (operations_with_ids / total_operations * 100) if total_operations > 0 else 100
-        factors.append(operation_id_score)
-        
-        # Factor 3: Reasonable path complexity
-        avg_path_complexity = 0
-        if paths:
-            complexities = []
-            for path in paths.keys():
-                segments = [seg for seg in path.split('/') if seg]
-                complexities.append(len(segments))
-            
-            avg_complexity = sum(complexities) / len(complexities)
-            # Optimal complexity is 3-4 segments
-            if 3 <= avg_complexity <= 4:
-                avg_path_complexity = 100
-            elif 2 <= avg_complexity <= 5:
-                avg_path_complexity = 80
-            else:
-                avg_path_complexity = 60
-        
-        factors.append(avg_path_complexity)
-        
-        return sum(factors) / len(factors) if factors else 0
-    
-    def _score_performance(self) -> None:
-        """Score API performance patterns (15% weight)."""
-        category = ScoreCategory.PERFORMANCE
-        score = CategoryScore(
-            category=category,
-            score=0.0,
-            max_score=100.0,
-            weight=self.category_weights[category]
-        )
-        
-        performance_checks = [
-            self._check_caching_headers(),
-            self._check_pagination_patterns(),
-            self._check_compression_support(),
-            self._check_efficiency_patterns(),
-            self._check_batch_operations()
-        ]
-        
-        valid_scores = [s for s in performance_checks if s is not None]
-        if valid_scores:
-            score.score = sum(valid_scores) / len(valid_scores)
-        
-        # Add recommendations
-        if score.score < 60:
-            score.recommendations.extend([
-                "Implement pagination for list endpoints",
-                "Add caching headers for cacheable responses",
-                "Consider batch operations for bulk updates"
-            ])
-        elif score.score < 80:
-            score.recommendations.extend([
-                "Review caching strategies for better performance",
-                "Consider field selection parameters for large responses"
-            ])
-        
-        self.scorecard.category_scores[category] = score
-    
-    def _check_caching_headers(self) -> float:
-        """Check caching header implementation."""
-        paths = self.spec.get('paths', {})
-        
-        get_operations = 0
-        cacheable_operations = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-            
-            get_operation = path_obj.get('get')
-            if get_operation and isinstance(get_operation, dict):
-                get_operations += 1
-                
-                # Check for caching-related headers in responses
-                responses = get_operation.get('responses', {})
-                for response in responses.values():
-                    if not isinstance(response, dict):
-                        continue
-                    
-                    headers = response.get('headers', {})
-                    cache_headers = {'cache-control', 'etag', 'last-modified', 'expires'}
-                    
-                    if any(header.lower() in cache_headers for header in headers.keys()):
-                        cacheable_operations += 1
-                        break
-        
-        return (cacheable_operations / get_operations * 100) if get_operations > 0 else 50
-    
-    def _check_pagination_patterns(self) -> float:
-        """Check pagination implementation."""
-        paths = self.spec.get('paths', {})
-        
-        collection_endpoints = 0
-        paginated_endpoints = 0
-        
-        for path, path_obj in paths.items():
-            if not isinstance(path_obj, dict):
-                continue
-            
-            # Identify collection endpoints
-            if '{' not in path:  # No path parameters = collection
-                get_operation = path_obj.get('get')
-                if get_operation and isinstance(get_operation, dict):
-                    collection_endpoints += 1
-                    
-                    # Check for pagination parameters
-                    parameters = get_operation.get('parameters', [])
-                    pagination_params = {'limit', 'offset', 'page', 'pagesize', 'per_page', 'cursor'}
-                    
-                    has_pagination = any(
-                        isinstance(param, dict) and param.get('name', '').lower() in pagination_params
-                        for param in parameters
-                    )
-                    
-                    if has_pagination:
-                        paginated_endpoints += 1
-        
-        return (paginated_endpoints / collection_endpoints * 100) if collection_endpoints > 0 else 100
-    
-    def _check_compression_support(self) -> float:
-        """Check compression support indicators."""
-        # This is speculative - OpenAPI doesn't directly specify compression
-        # Look for indicators that compression is considered
-        
-        servers = self.spec.get('servers', [])
-        
-        # Check if any server descriptions mention compression
-        compression_mentions = 0
-        for server in servers:
-            if isinstance(server, dict):
-                description = server.get('description', '').lower()
-                if any(term in description for term in ['gzip', 'compress', 'deflate']):
-                    compression_mentions += 1
-        
-        # Base score - assume compression is handled at server level
-        base_score = 70
-        
-        if compression_mentions > 0:
-            return min(base_score + (compression_mentions * 10), 100)
-        
-        return base_score
-    
-    def _check_efficiency_patterns(self) -> float:
-        """Check efficiency patterns like field selection."""
-        paths = self.spec.get('paths', {})
-        
-        total_get_operations = 0
-        operations_with_selection = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-            
-            get_operation = path_obj.get('get')
-            if get_operation and isinstance(get_operation, dict):
-                total_get_operations += 1
-                
-                # Check for field selection parameters
-                parameters = get_operation.get('parameters', [])
-                selection_params = {'fields', 'select', 'include', 'exclude'}
-                
-                has_selection = any(
-                    isinstance(param, dict) and param.get('name', '').lower() in selection_params
-                    for param in parameters
-                )
-                
-                if has_selection:
-                    operations_with_selection += 1
-        
-        return (operations_with_selection / total_get_operations * 100) if total_get_operations > 0 else 60
-    
-    def _check_batch_operations(self) -> float:
-        """Check for batch operation support."""
-        paths = self.spec.get('paths', {})
-        
-        # Look for batch endpoints
-        batch_indicators = ['batch', 'bulk', 'multi']
-        batch_endpoints = 0
-        
-        for path in paths.keys():
-            if any(indicator in path.lower() for indicator in batch_indicators):
-                batch_endpoints += 1
-        
-        # Look for array-based request bodies (indicating batch operations)
-        array_operations = 0
-        total_post_put_operations = 0
-        
-        for path_obj in paths.values():
-            if not isinstance(path_obj, dict):
-                continue
-            
-            for method in ['post', 'put', 'patch']:
-                operation = path_obj.get(method)
-                if operation and isinstance(operation, dict):
-                    total_post_put_operations += 1
-                    
-                    request_body = operation.get('requestBody', {})
-                    content = request_body.get('content', {})
-                    
-                    for media_obj in content.values():
-                        schema = media_obj.get('schema', {})
-                        if schema.get('type') == 'array':
-                            array_operations += 1
-                            break
-        
-        # Score based on presence of batch patterns
-        batch_score = min(batch_endpoints * 20, 60)  # Up to 60 points for explicit batch endpoints
-        
-        if total_post_put_operations > 0:
-            array_score = (array_operations / total_post_put_operations) * 40
-            batch_score += array_score
-        
-        return min(batch_score, 100)
-    
-    def generate_json_report(self) -> str:
-        """Generate JSON format scorecard."""
-        report_data = {
-            "overall": {
-                "score": round(self.scorecard.overall_score, 2),
-                "grade": self.scorecard.overall_grade,
-                "totalEndpoints": self.scorecard.total_endpoints
-            },
-            "api_info": self.scorecard.api_info,
-            "categories": {},
-            "topRecommendations": self.scorecard.get_top_recommendations()
-        }
-        
-        for category, score in self.scorecard.category_scores.items():
-            report_data["categories"][category.value] = {
-                "score": round(score.score, 2),
-                "grade": score.letter_grade,
-                "weight": score.weight,
-                "weightedScore": round(score.weighted_score, 2),
-                "issues": score.issues,
-                "recommendations": score.recommendations
-            }
-        
-        return json.dumps(report_data, indent=2)
-    
-    def generate_text_report(self) -> str:
-        """Generate human-readable scorecard report."""
-        lines = [
-            "═══════════════════════════════════════════════════════════════",
-            "                      API DESIGN SCORECARD",
-            "═══════════════════════════════════════════════════════════════",
-            f"API: {self.scorecard.api_info.get('title', 'Unknown')}",
-            f"Version: {self.scorecard.api_info.get('version', 'Unknown')}",
-            f"Total Endpoints: {self.scorecard.total_endpoints}",
-            "",
-            f"🏆 OVERALL GRADE: {self.scorecard.overall_grade} ({self.scorecard.overall_score:.1f}/100.0)",
-            "",
-            "═══════════════════════════════════════════════════════════════",
-            "DETAILED BREAKDOWN:",
-            "═══════════════════════════════════════════════════════════════"
-        ]
-        
-        # Sort categories by weight (most important first)
-        sorted_categories = sorted(
-            self.scorecard.category_scores.items(),
-            key=lambda x: x[1].weight,
-            reverse=True
-        )
-        
-        for category, score in sorted_categories:
-            category_name = category.value.title().replace('_', ' ')
-            
-            lines.extend([
-                "",
-                f"📊 {category_name.upper()} - Grade: {score.letter_grade} ({score.score:.1f}/100)",
-                f"   Weight: {score.weight}% | Contribution: {score.weighted_score:.1f} points",
-                "   " + "─" * 50
-            ])
-            
-            if score.recommendations:
-                lines.append("   💡 Recommendations:")
-                for rec in score.recommendations[:3]:  # Top 3 recommendations
-                    lines.append(f"      • {rec}")
-            else:
-                lines.append("   ✅ No specific recommendations - performing well!")
-        
-        # Overall assessment
-        lines.extend([
-            "",
-            "═══════════════════════════════════════════════════════════════",
-            "OVERALL ASSESSMENT:",
-            "═══════════════════════════════════════════════════════════════"
-        ])
-        
-        if self.scorecard.overall_grade == "A":
-            lines.extend([
-                "🏆 EXCELLENT! Your API demonstrates outstanding design quality.",
-                "   Continue following these best practices and consider sharing",
-                "   your approach as a reference for other teams."
-            ])
-        elif self.scorecard.overall_grade == "B":
-            lines.extend([
-                "✅ GOOD! Your API follows most best practices with room for",
-                "   minor improvements. Focus on the recommendations above",
-                "   to achieve excellence."
-            ])
-        elif self.scorecard.overall_grade == "C":
-            lines.extend([
-                "⚠️  FAIR! Your API has a solid foundation but several areas",
-                "   need improvement. Prioritize the high-weight categories",
-                "   for maximum impact."
-            ])
-        elif self.scorecard.overall_grade == "D":
-            lines.extend([
-                "❌ NEEDS IMPROVEMENT! Your API has significant issues that",
-                "   may impact developer experience and maintainability.",
-                "   Focus on consistency and documentation first."
-            ])
-        else:  # Grade F
-            lines.extend([
-                "🚨 CRITICAL ISSUES! Your API requires major redesign to meet",
-                "   basic quality standards. Consider comprehensive review",
-                "   of design principles and best practices."
-            ])
-        
-        # Top recommendations
-        top_recs = self.scorecard.get_top_recommendations(3)
-        if top_recs:
-            lines.extend([
-                "",
-                "🎯 TOP PRIORITY RECOMMENDATIONS:",
-                ""
-            ])
-            for i, rec in enumerate(top_recs, 1):
-                lines.append(f"   {i}. {rec}")
-        
-        lines.extend([
-            "",
-            "═══════════════════════════════════════════════════════════════",
-            f"Generated by API Scorecard Tool | Score: {self.scorecard.overall_grade} ({self.scorecard.overall_score:.1f}%)",
-            "═══════════════════════════════════════════════════════════════"
-        ])
-        
-        return "\n".join(lines)
-
-
-def main():
-    """Main CLI entry point."""
-    parser = argparse.ArgumentParser(
-        description="Generate comprehensive API design quality scorecard",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Examples:
-  python api_scorecard.py openapi.json
-  python api_scorecard.py --format json openapi.json > scorecard.json
-  python api_scorecard.py --output scorecard.txt openapi.json
-        """
-    )
-    
-    parser.add_argument(
-        'spec_file',
-        help='OpenAPI/Swagger specification file (JSON format)'
-    )
-    
-    parser.add_argument(
-        '--format',
-        choices=['text', 'json'],
-        default='text',
-        help='Output format (default: text)'
-    )
-    
-    parser.add_argument(
-        '--output',
-        help='Output file (default: stdout)'
-    )
-    
-    parser.add_argument(
-        '--min-grade',
-        choices=['A', 'B', 'C', 'D', 'F'],
-        help='Exit with code 1 if grade is below minimum'
-    )
-    
-    args = parser.parse_args()
-    
-    # Load specification file
-    try:
-        with open(args.spec_file, 'r') as f:
-            spec = json.load(f)
-    except FileNotFoundError:
-        print(f"Error: Specification file '{args.spec_file}' not found.", file=sys.stderr)
-        return 1
-    except json.JSONDecodeError as e:
-        print(f"Error: Invalid JSON in '{args.spec_file}': {e}", file=sys.stderr)
-        return 1
-    
-    # Initialize scoring engine and generate scorecard
-    engine = APIScoringEngine()
-    
-    try:
-        scorecard = engine.score_api(spec)
-    except Exception as e:
-        print(f"Error during scoring: {e}", file=sys.stderr)
-        return 1
-    
-    # Generate report
-    if args.format == 'json':
-        output = engine.generate_json_report()
-    else:
-        output = engine.generate_text_report()
-    
-    # Write output
-    if args.output:
-        try:
-            with open(args.output, 'w') as f:
-                f.write(output)
-            print(f"Scorecard written to {args.output}")
-        except IOError as e:
-            print(f"Error writing to '{args.output}': {e}", file=sys.stderr)
-            return 1
-    else:
-        print(output)
-    
-    # Check minimum grade requirement
-    if args.min_grade:
-        grade_order = ['F', 'D', 'C', 'B', 'A']
-        current_grade_index = grade_order.index(scorecard.overall_grade)
-        min_grade_index = grade_order.index(args.min_grade)
-        
-        if current_grade_index < min_grade_index:
-            print(f"Grade {scorecard.overall_grade} is below minimum required grade {args.min_grade}", file=sys.stderr)
-            return 1
-    
-    return 0
-
-
-if __name__ == '__main__':
-    sys.exit(main())