django-cfg 1.4.10__py3-none-any.whl → 1.4.11__py3-none-any.whl

django_cfg/modules/django_client/management/commands/validate_openapi.py

@@ -0,0 +1,343 @@
+"""
+Django management command for OpenAPI schema validation.
+
+Usage:
+    python manage.py validate_openapi                        # Check all serializers
+    python manage.py validate_openapi --app accounts         # Check specific app
+    python manage.py validate_openapi --fix                  # Auto-fix issues
+    python manage.py validate_openapi --fix --dry-run        # Preview fixes
+    python manage.py validate_openapi --report html          # Generate HTML report
+"""
+
+from django.core.management.base import BaseCommand, CommandError
+from pathlib import Path
+from typing import List, Optional
+
+
+class Command(BaseCommand):
+    """Validate and fix OpenAPI schema quality issues in DRF serializers."""
+
+    help = "Validate and auto-fix OpenAPI schema quality issues"
+
+    def add_arguments(self, parser):
+        """Add command arguments."""
+        # Scope options
+        parser.add_argument(
+            "--app",
+            type=str,
+            help="Check specific Django app only",
+        )
+
+        parser.add_argument(
+            "--file",
+            type=str,
+            help="Check specific file only",
+        )
+
+        parser.add_argument(
+            "--pattern",
+            type=str,
+            default="*serializers.py",
+            help="File pattern to match (default: *serializers.py)",
+        )
+
+        # Action options
+        parser.add_argument(
+            "--fix",
+            action="store_true",
+            help="Apply auto-fixes to issues",
+        )
+
+        parser.add_argument(
+            "--dry-run",
+            action="store_true",
+            help="Show what would be fixed without applying changes",
+        )
+
+        parser.add_argument(
+            "--no-confirm",
+            action="store_true",
+            help="Skip confirmation prompt when fixing",
+        )
+
+        # Reporting options
+        parser.add_argument(
+            "--report",
+            type=str,
+            choices=["console", "json", "html"],
+            default="console",
+            help="Report format (default: console)",
+        )
+
+        parser.add_argument(
+            "--output",
+            type=str,
+            help="Output file for JSON/HTML reports",
+        )
+
+        parser.add_argument(
+            "--summary",
+            action="store_true",
+            help="Show summary only (compact output)",
+        )
+
+        # Filtering options
+        parser.add_argument(
+            "--severity",
+            type=str,
+            choices=["error", "warning", "info"],
+            help="Filter by minimum severity level",
+        )
+
+        parser.add_argument(
+            "--rule",
+            type=str,
+            help="Check specific rule only (e.g., type-hint-001)",
+        )
+
+        parser.add_argument(
+            "--fixable-only",
+            action="store_true",
+            help="Show only auto-fixable issues",
+        )
+
+        # Utility options
+        parser.add_argument(
+            "--list-rules",
+            action="store_true",
+            help="List available validation rules and exit",
+        )
+
+        parser.add_argument(
+            "--verbose",
+            action="store_true",
+            help="Show detailed output",
+        )
+
+    def handle(self, *args, **options):
+        """Handle command execution."""
+        try:
+            # Import validation components
+            from django_cfg.modules.django_client.core.validation import (
+                ValidationChecker,
+                SafeFixer,
+                IssueReporter,
+                SafetyManager,
+            )
+
+            # List rules
+            if options["list_rules"]:
+                self._list_rules()
+                return
+
+            # Get workspace directory
+            workspace = self._get_workspace(options)
+
+            # Create checker
+            checker = ValidationChecker()
+
+            # Check files
+            self.stdout.write(self.style.SUCCESS("\n🔍 Scanning for issues...\n"))
+            issues = self._check_files(checker, workspace, options)
+
+            # Filter issues
+            issues = self._filter_issues(issues, options)
+
+            if not issues:
+                self.stdout.write(self.style.SUCCESS("✅ No issues found!\n"))
+                return
+
+            # Report issues
+            reporter = IssueReporter(use_colors=True)
+
+            if options["summary"]:
+                reporter.display_summary(issues)
+            elif options["report"] == "console":
+                reporter.display_console(
+                    issues,
+                    show_suggestions=True,
+                    group_by_file=True,
+                    verbose=options["verbose"]
+                )
+            elif options["report"] == "json":
+                output_path = self._get_output_path(options, "validation_report.json")
+                reporter.save_json(issues, output_path, include_stats=True)
+            elif options["report"] == "html":
+                output_path = self._get_output_path(options, "validation_report.html")
+                reporter.save_html(issues, output_path, title="OpenAPI Validation Report")
+
+            # Apply fixes if requested
+            if options["fix"]:
+                self._apply_fixes(issues, workspace, options)
+            elif not options["summary"]:
+                # Suggest fix command
+                fixable = checker.get_fixable_issues(issues)
+                if fixable:
+                    self.stdout.write(
+                        self.style.WARNING(
+                            f"\n💡 Tip: Run with --fix to auto-fix {len(fixable)} issue(s)"
+                        )
+                    )
+
+        except Exception as e:
+            raise CommandError(f"Validation failed: {e}")
+
+    def _list_rules(self):
+        """List available validation rules."""
+        from django_cfg.modules.django_client.core.validation import ValidationChecker
+
+        checker = ValidationChecker()
+
+        self.stdout.write(self.style.SUCCESS(f"\n📋 Available Validation Rules ({len(checker.rules)}):\n"))
+
+        for rule in checker.rules:
+            self.stdout.write(f"  • {rule.rule_id}: {rule.name}")
+            self.stdout.write(f"    {rule.description}")
+            self.stdout.write("")
+
+    def _get_workspace(self, options) -> Path:
+        """Get workspace directory to check."""
+        from django.conf import settings
+
+        if options["file"]:
+            # Specific file
+            file_path = Path(options["file"])
+            if not file_path.is_absolute():
+                file_path = Path.cwd() / file_path
+            return file_path.parent
+
+        if options["app"]:
+            # Specific app
+            from django.apps import apps
+            try:
+                app_config = apps.get_app_config(options["app"])
+                return Path(app_config.path)
+            except LookupError:
+                raise CommandError(f"App '{options['app']}' not found")
+
+        # Default: all apps in project
+        # Try BASE_DIR first, fallback to current directory
+        base_dir = getattr(settings, 'BASE_DIR', None)
+        if base_dir:
+            return Path(base_dir)
+        else:
+            return Path.cwd()
+
+    def _check_files(self, checker, workspace: Path, options) -> List:
+        """Check files for issues."""
+        from django_cfg.modules.django_client.core.validation import Issue
+
+        if options["file"]:
+            # Check specific file
+            file_path = Path(options["file"])
+            if not file_path.is_absolute():
+                file_path = Path.cwd() / file_path
+
+            if not file_path.exists():
+                raise CommandError(f"File not found: {file_path}")
+
+            return checker.check_file(file_path)
+
+        # Check directory
+        pattern = options["pattern"]
+        return checker.check_directory(workspace, pattern=pattern, recursive=True)
+
+    def _filter_issues(self, issues: List, options) -> List:
+        """Filter issues based on options."""
+        from django_cfg.modules.django_client.core.validation import Severity
+
+        filtered = issues
+
+        # Filter by severity
+        if options["severity"]:
+            min_severity = Severity[options["severity"].upper()]
+            severity_order = {Severity.ERROR: 3, Severity.WARNING: 2, Severity.INFO: 1}
+            min_level = severity_order[min_severity]
+            filtered = [
+                i for i in filtered
+                if severity_order[i.severity] >= min_level
+            ]
+
+        # Filter by rule
+        if options["rule"]:
+            filtered = [i for i in filtered if i.rule_id == options["rule"]]
+
+        # Filter by fixability
+        if options["fixable_only"]:
+            filtered = [i for i in filtered if i.auto_fixable]
+
+        return filtered
+
+    def _get_output_path(self, options, default_name: str) -> Path:
+        """Get output file path."""
+        if options["output"]:
+            output = Path(options["output"])
+            if not output.is_absolute():
+                output = Path.cwd() / output
+            return output
+
+        return Path.cwd() / default_name
+
+    def _apply_fixes(self, issues: List, workspace: Path, options):
+        """Apply fixes to issues."""
+        from django_cfg.modules.django_client.core.validation import (
+            SafeFixer,
+            SafetyManager,
+            ValidationChecker,
+        )
+
+        # Get fixable issues
+        checker = ValidationChecker()
+        fixable = checker.get_fixable_issues(issues)
+
+        if not fixable:
+            self.stdout.write(self.style.WARNING("\n⚠️  No auto-fixable issues found"))
+            return
+
+        # Create safety manager and fixer
+        safety = SafetyManager(workspace)
+        fixer = SafeFixer(safety)
+
+        # Apply fixes
+        dry_run = options["dry_run"]
+        confirm = not options["no_confirm"]
+
+        self.stdout.write(self.style.SUCCESS("\n🔧 Applying fixes...\n"))
+
+        results = fixer.fix_issues(
+            fixable,
+            dry_run=dry_run,
+            confirm=confirm,
+            verbose=options["verbose"]
+        )
+
+        # Show results
+        if dry_run:
+            self.stdout.write(
+                self.style.WARNING(
+                    f"\n🔍 Dry run completed - would fix {results['skipped']} issue(s)"
+                )
+            )
+        else:
+            if results['fixed'] > 0:
+                self.stdout.write(
+                    self.style.SUCCESS(
+                        f"\n✅ Successfully fixed {results['fixed']} issue(s)!"
+                    )
+                )
+
+            if results['failed'] > 0:
+                self.stdout.write(
+                    self.style.ERROR(
+                        f"\n❌ Failed to fix {results['failed']} issue(s)"
+                    )
+                )
+                for error in results['errors']:
+                    self.stdout.write(f"  - {error}")
+
+            if results['skipped'] > 0:
+                self.stdout.write(
+                    self.style.WARNING(
+                        f"\n⏭️  Skipped {results['skipped']} issue(s)"
+                    )
+                )

django_cfg/modules/django_client/spectacular/__init__.py

@@ -0,0 +1,9 @@
+"""
+DRF Spectacular postprocessing hooks for django-cfg.
+
+Auto-fixes for OpenAPI schema generation.
+"""
+
+from .enum_naming import auto_fix_enum_names
+
+__all__ = ['auto_fix_enum_names']

django_cfg/modules/django_client/spectacular/enum_naming.py

@@ -0,0 +1,192 @@
+"""
+Auto-fix enum naming collisions in OpenAPI schema.
+
+This postprocessing hook automatically generates unique, descriptive enum names
+based on model names to avoid collisions like "Status50eEnum", "StatusA98Enum".
+
+Instead generates: "ProductStatusEnum", "OrderStatusEnum", "PostStatusEnum", etc.
+"""
+
+import logging
+from typing import Dict, Any, Optional
+import re
+
+logger = logging.getLogger(__name__)
+
+
+def auto_fix_enum_names(result: Dict[str, Any], generator, request, public) -> Dict[str, Any]:
+    """
+    DRF Spectacular postprocessing hook to auto-fix enum naming collisions.
+
+    Automatically detects and fixes enum naming collisions by using model names.
+
+    Args:
+        result: OpenAPI schema dict
+        generator: Schema generator instance
+        request: HTTP request
+        public: Whether schema is public
+
+    Returns:
+        Modified OpenAPI schema with fixed enum names
+
+    Example:
+        Before: Status50eEnum, StatusA98Enum (collision hashes)
+        After:  ProductStatusEnum, OrderStatusEnum (descriptive names)
+    """
+
+    if 'components' not in result or 'schemas' not in result['components']:
+        return result
+
+    schemas = result['components']['schemas']
+
+    # Track enum references and their sources (model + field)
+    enum_sources: Dict[str, list] = {}  # enum_name -> [(model_name, field_name, choices)]
+    enum_renames: Dict[str, str] = {}   # old_name -> new_name
+
+    # Step 1: Find all enums and their sources
+    for schema_name, schema in schemas.items():
+        if schema.get('type') == 'object' and 'properties' in schema:
+            # This is a model schema
+            model_name = _extract_model_name(schema_name)
+
+            for field_name, field_schema in schema['properties'].items():
+                # Check if field references an enum
+                if '$ref' in field_schema:
+                    enum_ref = field_schema['$ref']
+                    if '#/components/schemas/' in enum_ref:
+                        enum_name = enum_ref.split('/')[-1]
+
+                        # Track enum source
+                        if enum_name not in enum_sources:
+                            enum_sources[enum_name] = []
+
+                        enum_sources[enum_name].append((model_name, field_name))
+
+    # Step 2: Detect collisions and generate better names
+    for enum_name, sources in enum_sources.items():
+        # Check if enum looks like a collision (contains hash or generic name)
+        if _is_collision_enum(enum_name):
+            # Multiple models use this enum - need unique names
+            if len(sources) == 1:
+                # Single source - generate descriptive name
+                model_name, field_name = sources[0]
+                new_name = _generate_enum_name(model_name, field_name)
+                enum_renames[enum_name] = new_name
+
+                logger.debug(f"  Renaming {enum_name} -> {new_name} (from {model_name}.{field_name})")
+
+    # Step 3: Apply renames to schema
+    if enum_renames:
+        logger.info(f"🔧 Auto-fixed {len(enum_renames)} enum naming collision(s)")
+        _apply_enum_renames(result, enum_renames)
+
+    return result
+
+
+def _extract_model_name(schema_name: str) -> str:
+    """
+    Extract model name from schema name.
+
+    Examples:
+        "Product" -> "Product"
+        "ProductDetail" -> "Product"
+        "PaginatedProductList" -> "Product"
+    """
+    # Remove common prefixes/suffixes
+    name = schema_name
+
+    # Remove pagination wrapper
+    if name.startswith('Paginated') and name.endswith('List'):
+        name = name[9:-4]  # Remove "Paginated" and "List"
+
+    # Remove common suffixes
+    for suffix in ['Serializer', 'Detail', 'List', 'Create', 'Update']:
+        if name.endswith(suffix):
+            name = name[:-len(suffix)]
+            break
+
+    return name
+
+
+def _is_collision_enum(enum_name: str) -> bool:
+    """
+    Check if enum name looks like a collision (contains hash).
+
+    Examples:
+        "Status50eEnum" -> True (has hash)
+        "StatusA98Enum" -> True (has hash)
+        "ProductStatusEnum" -> False (descriptive)
+    """
+    # Check if enum contains hash-like patterns (3+ hex chars)
+    if re.search(r'[0-9A-Fa-f]{3,}Enum$', enum_name):
+        return True
+
+    # Check for generic single-word enums that are likely collisions
+    # (e.g., "StatusEnum" without model prefix)
+    if re.match(r'^[A-Z][a-z]+Enum$', enum_name):
+        # Single word + Enum - likely collision
+        return True
+
+    return False
+
+
+def _generate_enum_name(model_name: str, field_name: str) -> str:
+    """
+    Generate descriptive enum name from model and field.
+
+    Examples:
+        ("Product", "status") -> "ProductStatusEnum"
+        ("Order", "status") -> "OrderStatusEnum"
+        ("Post", "status") -> "PostStatusEnum"
+    """
+    # Capitalize field name
+    field_capitalized = field_name.capitalize()
+
+    # Combine: ModelName + FieldName + Enum
+    return f"{model_name}{field_capitalized}Enum"
+
+
+def _apply_enum_renames(schema: Dict[str, Any], renames: Dict[str, str]) -> None:
+    """
+    Apply enum renames throughout the schema.
+
+    Renames both:
+    1. Schema component definitions (components/schemas/OldName -> NewName)
+    2. All references to renamed enums ($ref: #/components/schemas/OldName)
+    """
+    if 'components' not in schema or 'schemas' not in schema['components']:
+        return
+
+    schemas = schema['components']['schemas']
+
+    # Step 1: Rename schema definitions
+    for old_name, new_name in renames.items():
+        if old_name in schemas:
+            schemas[new_name] = schemas.pop(old_name)
+            logger.debug(f"  Renamed schema: {old_name} -> {new_name}")
+
+    # Step 2: Update all $ref references
+    _update_refs_recursive(schema, renames)
+
+
+def _update_refs_recursive(obj: Any, renames: Dict[str, str]) -> None:
+    """
+    Recursively update all $ref references in schema.
+    """
+    if isinstance(obj, dict):
+        # Check if this dict contains a $ref
+        if '$ref' in obj:
+            ref = obj['$ref']
+            if '#/components/schemas/' in ref:
+                enum_name = ref.split('/')[-1]
+                if enum_name in renames:
+                    obj['$ref'] = f"#/components/schemas/{renames[enum_name]}"
+
+        # Recurse into dict values
+        for value in obj.values():
+            _update_refs_recursive(value, renames)
+
+    elif isinstance(obj, list):
+        # Recurse into list items
+        for item in obj:
+            _update_refs_recursive(item, renames)

django_cfg/modules/django_client/urls.py

@@ -0,0 +1,72 @@
+"""
+Django URL integration.
+
+Provides URL patterns for OpenAPI schema generation.
+Each configured group gets its own schema endpoint.
+"""
+
+from typing import List, Any
+
+
+def _is_django_configured() -> bool:
+    """Check if Django settings are configured."""
+    try:
+        from django.conf import settings
+        return settings.configured
+    except ImportError:
+        return False
+
+
+def get_openapi_urls() -> List[Any]:
+    """
+    Get URL patterns for OpenAPI schema generation.
+
+    Creates URLs for each configured group:
+    - /openapi/{group_name}/schema/ - JSON schema
+
+    Returns:
+        List of Django URL patterns
+    """
+    try:
+        from django.urls import path
+        from drf_spectacular.views import SpectacularAPIView
+        from django_cfg.modules.django_client.core import get_openapi_service
+    except ImportError:
+        return []
+
+    service = get_openapi_service()
+
+    if not service.config or not service.is_enabled():
+        return []
+
+    patterns = []
+
+    for group_name in service.get_group_names():
+        group_config = service.get_group(group_name)
+        if not group_config:
+            continue
+
+        # Schema endpoint for each group
+        patterns.append(
+            path(
+                f'{group_name}/schema/',
+                SpectacularAPIView.as_view(
+                    urlconf=f'openapi_group_{group_name}',
+                    api_version=group_config.version,
+                ),
+                name=f'openapi-schema-{group_name}',
+            )
+        )
+
+    return patterns
+
+
+# Export urlpatterns for django.urls.include()
+# Only create urlpatterns if Django is configured
+if _is_django_configured():
+    urlpatterns = get_openapi_urls()
+else:
+    urlpatterns = []
+
+
+__all__ = ["get_openapi_urls", "urlpatterns"]