jentic-openapi-validator 1.0.0a7__py3-none-any.whl

jentic/apitools/openapi/validator/backends/base.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from jentic.apitools.openapi.validator.core.diagnostics import ValidationResult
+
+
+__all__ = ["BaseValidatorBackend"]
+
+
+class BaseValidatorBackend(ABC):
+    """Interface that all Validator backends must implement."""
+
+    @abstractmethod
+    def validate(
+        self, document: str | dict, *, base_url: str | None = None, target: str | None = None
+    ) -> ValidationResult:
+        """Validate an OpenAPI document given by URI or file path or text.
+        Returns a ValidationResult (could be a list of errors, or an object)."""
+        ...
+
+    @staticmethod
+    @abstractmethod
+    def accepts() -> Sequence[str]:
+        """Return the document formats this backend can accept.
+
+        Returns:
+            Sequence of format identifiers (e.g., "uri", "text", "dict")
+        """
+        ...

jentic/apitools/openapi/validator/backends/default/__init__.py

@@ -0,0 +1,204 @@
+"""
+Default OpenAPI validator backend with rule-based validation system.
+
+This backend provides a collection of validation rules for common OpenAPI
+specification issues including structural validation, server validation,
+and security validation.
+"""
+
+from typing import Literal
+
+from lsprotocol import types as lsp
+
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.parser.core.exceptions import DocumentLoadError, DocumentParseError
+
+from ...core.diagnostics import JenticDiagnostic, ValidationResult
+from ..base import BaseValidatorBackend
+from .rules import RuleRegistry
+from .rules.security import SecuritySchemeReferenceRule, UnusedSecuritySchemeRule
+from .rules.server import ServerUrlRule
+from .rules.structural import InfoObjectRule, PathsRule
+
+
+__all__ = ["DefaultOpenAPIValidatorBackend"]
+
+
+class DefaultOpenAPIValidatorBackend(BaseValidatorBackend):
+    """
+    Default OpenAPI validator backend using a rule-based validation system.
+
+    This validator applies a set of predefined rules to check for common
+    issues in OpenAPI specifications. Rules cover:
+    - Structural validation (info, paths)
+    - Server validation (servers array, URLs)
+    - Security validation (scheme references, unused schemes)
+
+    The validator can be customized by providing a custom RuleRegistry
+    with different rules.
+    """
+
+    def __init__(
+        self, rule_registry: RuleRegistry | None = None, parser: OpenAPIParser | None = None
+    ):
+        """
+        Initialize the default OpenAPI validator.
+
+        Args:
+            rule_registry: Optional custom rule registry. If None, uses default rules.
+            parser: Optional OpenAPIParser instance. If None, creates a default parser.
+        """
+        if rule_registry is None:
+            rule_registry = self._create_default_registry()
+        self.registry = rule_registry
+        self.parser = parser if parser else OpenAPIParser()
+
+    def validate(
+        self, document: str | dict, *, base_url: str | None = None, target: str | None = None
+    ) -> ValidationResult:
+        """
+        Validate an OpenAPI document using the registered rules.
+
+        Args:
+            document: Path to the OpenAPI document file to validate, or dict containing the document
+            base_url: Optional base URL for resolving references
+            target: Optional target identifier for validation context
+
+        Returns:
+            ValidationResult containing diagnostics for all rule violations
+
+        Raises:
+            TypeError: If document type is not supported
+        """
+        if isinstance(document, str):
+            return self._validate_uri(document, base_url=base_url, target=target)
+        elif isinstance(document, dict):
+            return self._validate_dict(document, base_url=base_url, target=target)
+        else:
+            raise TypeError(f"Unsupported document type: {type(document)!r}")
+
+    @staticmethod
+    def accepts() -> list[Literal["uri", "dict"]]:
+        """
+        Return the document formats this validator accepts.
+
+        Returns:
+            Sequence of supported document format identifiers:
+            - "uri": File path or URI pointing to OpenAPI Document
+            - "dict": Python dictionary containing OpenAPI Document data
+        """
+        return ["uri", "dict"]
+
+    def _validate_uri(
+        self, document: str, *, base_url: str | None = None, target: str | None = None
+    ) -> ValidationResult:
+        """
+        Validate an OpenAPI document from a URI or file path.
+
+        Args:
+            document: Path to the OpenAPI document file or URI
+            base_url: Optional base URL for resolving references
+            target: Optional target identifier for validation context
+
+        Returns:
+            ValidationResult containing diagnostics for all rule violations
+        """
+        try:
+            # Check if parser backend supports URI directly
+            if "uri" in self.parser.backend.accepts():
+                # Let parser handle URI loading
+                document_dict = self.parser.parse(document)
+            else:
+                # Manually load URI and parse the text
+                document_text = self.parser.load_uri(document)
+                document_dict = self.parser.parse(document_text)
+
+            # Validate the parsed document
+            return self._validate_dict(document_dict, base_url=base_url, target=target)
+
+        except (DocumentParseError, DocumentLoadError) as e:
+            # Handle document parsing/loading errors
+            diagnostic = JenticDiagnostic(
+                range=lsp.Range(
+                    start=lsp.Position(line=0, character=0),
+                    end=lsp.Position(line=0, character=12),
+                ),
+                severity=lsp.DiagnosticSeverity.Error,
+                code="document-parse-error",
+                source="default-validator",
+                message=f"Failed to parse document: {str(e)}",
+            )
+            diagnostic.set_target(target)
+            return ValidationResult(diagnostics=[diagnostic])
+        except Exception as e:
+            # Handle any other unexpected errors
+            diagnostic = JenticDiagnostic(
+                range=lsp.Range(
+                    start=lsp.Position(line=0, character=0),
+                    end=lsp.Position(line=0, character=12),
+                ),
+                severity=lsp.DiagnosticSeverity.Error,
+                code="default-validator-error",
+                source="default-validator",
+                message=f"Unexpected error: {str(e)}",
+            )
+            diagnostic.set_target(target)
+            return ValidationResult(diagnostics=[diagnostic])
+
+    def _validate_dict(
+        self, document: dict, *, base_url: str | None = None, target: str | None = None
+    ) -> ValidationResult:
+        """
+        Validate an OpenAPI document from a dictionary.
+
+        Args:
+            document: The OpenAPI document as a dictionary
+            base_url: Optional base URL for resolving references (not used)
+            target: Optional target identifier for validation context
+
+        Returns:
+            ValidationResult containing diagnostics for all rule violations
+        """
+        try:
+            # Run all rules through the registry
+            diagnostics = self.registry.validate(document, target=target)
+            return ValidationResult(diagnostics=diagnostics)
+
+        except Exception as e:
+            # Catch any unexpected errors during validation
+            msg = str(e)
+            diagnostic = JenticDiagnostic(
+                range=lsp.Range(
+                    start=lsp.Position(line=0, character=0),
+                    end=lsp.Position(line=0, character=12),
+                ),
+                severity=lsp.DiagnosticSeverity.Error,
+                code="default-validator-error",
+                source="default-validator",
+                message=msg,
+            )
+            diagnostic.set_target(target)
+            return ValidationResult(diagnostics=[diagnostic])
+
+    @staticmethod
+    def _create_default_registry() -> RuleRegistry:
+        """
+        Create the default rule registry with all standard rules.
+
+        Returns:
+            A RuleRegistry with all default validation rules registered
+        """
+        registry = RuleRegistry(source="default-validator")
+
+        # Register structural rules
+        registry.register(InfoObjectRule())
+        registry.register(PathsRule())
+
+        # Register server rules (only validate format if servers exist)
+        registry.register(ServerUrlRule())
+
+        # Register security rules
+        registry.register(SecuritySchemeReferenceRule())
+        registry.register(UnusedSecuritySchemeRule())
+
+        return registry

jentic/apitools/openapi/validator/backends/default/rules/__init__.py

@@ -0,0 +1,182 @@
+"""
+Validation rules system for the default OpenAPI validator backend.
+
+This module provides the infrastructure for defining and executing validation rules
+on OpenAPI specifications. Rules are modular, testable, and composable.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from lsprotocol import types as lsp
+
+from ....core.diagnostics import JenticDiagnostic
+
+
+__all__ = ["BaseRule", "RuleRegistry", "ValidationIssue"]
+
+
+@dataclass
+class ValidationIssue:
+    """
+    Represents a validation issue found by a rule.
+
+    This is a lightweight data structure that captures the essential information
+    about a validation problem. It will be converted to a JenticDiagnostic
+    by the rule registry.
+
+    Attributes:
+        code: Error code (e.g., "MISSING_SERVER_URL")
+        message: Human-readable error message
+        severity: Diagnostic severity level
+        path: JSON path to the problematic element (e.g., ["servers", 0, "url"])
+        fixable: Whether this issue can be automatically fixed
+    """
+
+    code: str
+    message: str
+    severity: lsp.DiagnosticSeverity = lsp.DiagnosticSeverity.Error
+    path: list[str | int] = field(default_factory=list)
+    fixable: bool = True
+
+    def to_diagnostic(self, source: str, target: str | None = None) -> JenticDiagnostic:
+        """
+        Convert this ValidationIssue to a JenticDiagnostic.
+
+        Args:
+            source: Source identifier for the diagnostic (e.g., "default-validator")
+            target: Optional target identifier for validation context
+
+        Returns:
+            A JenticDiagnostic instance ready to be returned to the user
+        """
+        diagnostic = JenticDiagnostic(
+            range=lsp.Range(
+                start=lsp.Position(line=0, character=0),
+                end=lsp.Position(line=0, character=0),
+            ),
+            severity=self.severity,
+            code=self.code,
+            source=source,
+            message=self.message,
+        )
+        diagnostic.set_path(self.path)
+        diagnostic.set_target(target)
+        diagnostic.set_fixable(self.fixable)
+        return diagnostic
+
+
+class BaseRule(ABC):
+    """
+    Abstract base class for validation rules.
+
+    Each rule should focus on validating a specific aspect of the OpenAPI specification.
+    Rules are designed to be stateless and reusable.
+
+    Subclasses must implement the `validate` method which examines the spec
+    and returns a list of ValidationIssue objects for any problems found.
+    """
+
+    @property
+    @abstractmethod
+    def rule_id(self) -> str:
+        """
+        Return a machine-readable identifier for this rule.
+
+        The rule ID should be in dash-case (kebab-case) format for consistency
+        with other validation tools like Redocly.
+
+        Returns:
+            Rule identifier (e.g., "server-url-validation")
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """
+        Return a human-readable name for this rule.
+
+        Returns:
+            Rule name (e.g., "Server URL Validation")
+        """
+        ...
+
+    @abstractmethod
+    def validate(self, spec_data: dict[str, Any]) -> list[ValidationIssue]:
+        """
+        Validate the OpenAPI specification.
+
+        Args:
+            spec_data: The parsed OpenAPI specification as a dictionary
+
+        Returns:
+            List of ValidationIssue objects for any problems found.
+            Empty list if no issues.
+        """
+        ...
+
+
+class RuleRegistry:
+    """
+    Registry for managing and executing validation rules.
+
+    The registry maintains a collection of validation rules and provides
+    methods to execute them against OpenAPI specifications.
+    """
+
+    def __init__(self, source: str = "default-validator"):
+        """
+        Initialize the rule registry.
+
+        Args:
+            source: Source identifier for diagnostics (default: "default-validator")
+        """
+        self.source = source
+        self.rules: list[BaseRule] = []
+
+    def register(self, rule: BaseRule) -> None:
+        """
+        Register a validation rule.
+
+        Args:
+            rule: The rule to register
+        """
+        self.rules.append(rule)
+
+    def register_all(self, rules: list[BaseRule]) -> None:
+        """
+        Register multiple validation rules at once.
+
+        Args:
+            rules: List of rules to register
+        """
+        self.rules.extend(rules)
+
+    def validate(
+        self, spec_data: dict[str, Any], target: str | None = None
+    ) -> list[JenticDiagnostic]:
+        """
+        Run all registered rules against the specification.
+
+        Args:
+            spec_data: The parsed OpenAPI specification as a dictionary
+            target: Optional target identifier for validation context
+
+        Returns:
+            List of JenticDiagnostic objects for all issues found across all rules
+        """
+        diagnostics: list[JenticDiagnostic] = []
+
+        for rule in self.rules:
+            issues = rule.validate(spec_data)
+            for issue in issues:
+                diagnostic = issue.to_diagnostic(source=self.source, target=target)
+                diagnostics.append(diagnostic)
+
+        return diagnostics
+
+    def clear(self) -> None:
+        """Clear all registered rules."""
+        self.rules.clear()

jentic/apitools/openapi/validator/backends/default/rules/security.py

@@ -0,0 +1,200 @@
+"""
+Security validation rules for OpenAPI specifications.
+
+These rules validate security schemes and their usage throughout the specification.
+"""
+
+from typing import Any
+
+from lsprotocol import types as lsp
+
+from . import BaseRule, ValidationIssue
+
+
+__all__ = ["SecuritySchemeReferenceRule", "UnusedSecuritySchemeRule"]
+
+
+# HTTP methods defined in OpenAPI 3.x specification
+_HTTP_METHODS = {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
+
+
+class SecuritySchemeReferenceRule(BaseRule):
+    """
+    Validates that all security scheme references point to defined schemes.
+
+    Checks both global security requirements and operation-level security requirements
+    to ensure they only reference schemes defined in components.securitySchemes.
+    """
+
+    @property
+    def rule_id(self) -> str:
+        return "security-scheme-reference"
+
+    @property
+    def name(self) -> str:
+        return "Security Scheme Reference Validation"
+
+    def validate(self, spec_data: dict[str, Any]) -> list[ValidationIssue]:
+        issues: list[ValidationIssue] = []
+
+        # Get defined security schemes
+        components = spec_data.get("components", {})
+        security_schemes = components.get("securitySchemes", {})
+        defined_schemes: set[str] = (
+            set(security_schemes.keys()) if isinstance(security_schemes, dict) else set()
+        )
+
+        # Check global security requirements
+        issues.extend(self._check_global_security(spec_data, defined_schemes))
+
+        # Check operation-level security requirements
+        issues.extend(self._check_operation_security(spec_data, defined_schemes))
+
+        return issues
+
+    @staticmethod
+    def _check_global_security(
+        spec_data: dict[str, Any], defined_schemes: set[str]
+    ) -> list[ValidationIssue]:
+        """Check global security requirements."""
+        issues: list[ValidationIssue] = []
+        global_security = spec_data.get("security", [])
+
+        if not isinstance(global_security, list):
+            return issues
+
+        for sec_req in global_security:
+            if not isinstance(sec_req, dict):
+                continue
+
+            for scheme in sec_req.keys():
+                if scheme not in defined_schemes:
+                    issues.append(
+                        ValidationIssue(
+                            code="UNDEFINED_SECURITY_SCHEME_REFERENCE",
+                            message=f"Global security requirement references undefined scheme '{scheme}'.",
+                            severity=lsp.DiagnosticSeverity.Error,
+                            path=["security"],
+                            fixable=False,
+                        )
+                    )
+
+        return issues
+
+    @staticmethod
+    def _check_operation_security(
+        spec_data: dict[str, Any], defined_schemes: set[str]
+    ) -> list[ValidationIssue]:
+        """Check operation-level security requirements."""
+        issues: list[ValidationIssue] = []
+        paths = spec_data.get("paths", {})
+
+        if not isinstance(paths, dict):
+            return issues
+
+        for path_str, path_item in paths.items():
+            if not isinstance(path_item, dict):
+                continue
+
+            for method, operation in path_item.items():
+                if method not in _HTTP_METHODS:
+                    continue
+
+                if not isinstance(operation, dict):
+                    continue
+
+                op_security = operation.get("security", [])
+                if not isinstance(op_security, list):
+                    continue
+
+                for sec_req in op_security:
+                    if not isinstance(sec_req, dict):
+                        continue
+
+                    for scheme in sec_req.keys():
+                        if scheme not in defined_schemes:
+                            issues.append(
+                                ValidationIssue(
+                                    code="UNDEFINED_SECURITY_SCHEME_REFERENCE",
+                                    message=f"Operation '{method.upper()}' at path '{path_str}' references undefined scheme '{scheme}'.",
+                                    severity=lsp.DiagnosticSeverity.Error,
+                                    path=[
+                                        "paths",
+                                        path_str,
+                                        method,
+                                        "security",
+                                    ],
+                                    fixable=False,
+                                )
+                            )
+
+        return issues
+
+
+class UnusedSecuritySchemeRule(BaseRule):
+    """
+    Detects security schemes that are defined but never used.
+
+    This is a warning-level rule that helps identify potentially dead code
+    in the security scheme definitions.
+    """
+
+    @property
+    def rule_id(self) -> str:
+        return "unused-security-scheme"
+
+    @property
+    def name(self) -> str:
+        return "Unused Security Scheme Detection"
+
+    def validate(self, spec_data: dict[str, Any]) -> list[ValidationIssue]:
+        issues: list[ValidationIssue] = []
+
+        # Get defined security schemes
+        components = spec_data.get("components", {})
+        security_schemes = components.get("securitySchemes", {})
+        defined_schemes: set[str] = (
+            set(security_schemes.keys()) if isinstance(security_schemes, dict) else set()
+        )
+
+        # Collect all referenced schemes
+        referenced_schemes: set[str] = set()
+
+        # Check global security
+        global_security = spec_data.get("security", [])
+        if isinstance(global_security, list):
+            for sec_req in global_security:
+                if isinstance(sec_req, dict):
+                    referenced_schemes.update(sec_req.keys())
+
+        # Check operation-level security
+        paths = spec_data.get("paths", {})
+        if isinstance(paths, dict):
+            for path_item in paths.values():
+                if not isinstance(path_item, dict):
+                    continue
+
+                for method, operation in path_item.items():
+                    if method not in _HTTP_METHODS or not isinstance(operation, dict):
+                        continue
+
+                    op_security = operation.get("security", [])
+                    if isinstance(op_security, list):
+                        for sec_req in op_security:
+                            if isinstance(sec_req, dict):
+                                referenced_schemes.update(sec_req.keys())
+
+        # Find unused schemes
+        unused = defined_schemes - referenced_schemes
+        for scheme in unused:
+            issues.append(
+                ValidationIssue(
+                    code="UNUSED_SECURITY_SCHEME_DEFINED",
+                    message=f"Security scheme '{scheme}' is defined in components.securitySchemes but not used in any security requirement.",
+                    severity=lsp.DiagnosticSeverity.Warning,
+                    path=["components", "securitySchemes", scheme],
+                    fixable=True,
+                )
+            )
+
+        return issues