actions/validate-inputs/docs/DEVELOPER_GUIDE.md

Developer Guide - Adding New Validators

Table of Contents

1. Quick Start
2. Creating a Core Validator
3. Creating a Custom Validator
4. Adding Convention Patterns
5. Writing Tests
6. Debugging
7. Common Patterns

Quick Start

Adding validation for a new input type

1. Check if existing validator covers it:

   # Search for similar validation patterns
   grep -r "validate_.*" validate-inputs/validators/
   

2. Use convention-based detection (easiest):

   • Name your input following conventions (e.g., my-token, api-version)
   • System automatically uses appropriate validator

3. Create custom validator (for complex logic):

   # Create CustomValidator.py in your action directory
   touch my-action/CustomValidator.py
   

Creating a Core Validator

Step 1: Create the Validator File

Create validate-inputs/validators/mytype.py:

"""Validator for MyType inputs."""

from __future__ import annotations
import re
from typing import Any

from .base import BaseValidator


class MyTypeValidator(BaseValidator):
    """Validates MyType-specific inputs."""

    def __init__(self, action_type: str = "") -> None:
        """Initialize the MyType validator."""
        super().__init__(action_type)

    def validate_inputs(self, inputs: dict[str, str]) -> bool:
        """Validate MyType inputs based on conventions.

        Args:
            inputs: Dictionary of input names to values

        Returns:
            True if all validations pass, False otherwise
        """
        valid = True

        for input_name, value in inputs.items():
            # Check if this input should be validated by this validator
            if self._should_validate(input_name):
                if not self.validate_mytype(value, input_name):
                    valid = False

        return valid

    def _should_validate(self, input_name: str) -> bool:
        """Check if input should be validated by this validator."""
        # Define patterns that trigger this validator
        patterns = [
            "mytype",
            "-mytype",
            "mytype-",
        ]

        name_lower = input_name.lower()
        return any(pattern in name_lower for pattern in patterns)

    def validate_mytype(self, value: str, field_name: str) -> bool:
        """Validate a MyType value.

        Args:
            value: The value to validate
            field_name: Name of the field being validated

        Returns:
            True if valid, False otherwise
        """
        # Allow empty for optional fields
        if not value or not value.strip():
            return True

        # Allow GitHub Actions expressions
        if self.is_github_expression(value):
            return True

        # Your validation logic here
        pattern = r"^mytype-[a-z0-9]+$"
        if not re.match(pattern, value):
            self.add_error(
                f"Invalid MyType format for '{field_name}': {value}. "
                f"Expected format: mytype-xxxxx"
            )
            return False

        return True

Step 2: Register the Validator

Add to validate-inputs/validators/__init__.py:

from .mytype import MyTypeValidator

__all__ = [
    # ... existing validators ...
    "MyTypeValidator",
]

Step 3: Add Convention Patterns

Update validate-inputs/validators/conventions.py:

# In ConventionBasedValidator.PATTERNS dict:
PATTERNS = {
    # Exact matches (highest priority)
    "exact": {
        # ... existing patterns ...
        "mytype-config": "mytype",
    },

    # Prefix patterns
    "prefix": {
        # ... existing patterns ...
        "mytype-": "mytype",
    },

    # Suffix patterns
    "suffix": {
        # ... existing patterns ...
        "-mytype": "mytype",
    },
}

# In get_validator_class method:
validator_map = {
    # ... existing mappings ...
    "mytype": MyTypeValidator,
}

Creating a Custom Validator

For Complex Action-Specific Logic

Create my-action/CustomValidator.py:

"""Custom validator for my-action.

This validator handles complex validation logic specific to my-action.
"""

from __future__ import annotations
from pathlib import Path
import sys

# Add validate-inputs directory to path
validate_inputs_path = Path(__file__).parent.parent / "validate-inputs"
sys.path.insert(0, str(validate_inputs_path))

from validators.base import BaseValidator
from validators.version import VersionValidator
from validators.token import TokenValidator


class CustomValidator(BaseValidator):
    """Custom validator for my-action."""

    def __init__(self, action_type: str = "my-action") -> None:
        """Initialize the custom validator."""
        super().__init__(action_type)
        # Initialize sub-validators
        self.version_validator = VersionValidator(action_type)
        self.token_validator = TokenValidator(action_type)

    def validate_inputs(self, inputs: dict[str, str]) -> bool:
        """Validate my-action specific inputs.

        Args:
            inputs: Dictionary of input names to values

        Returns:
            True if all validations pass, False otherwise
        """
        valid = True

        # Validate required inputs
        valid &= self.validate_required_inputs(inputs)

        # Use sub-validators
        if inputs.get("api-token"):
            if not self.token_validator.validate_github_token(
                inputs["api-token"], "api-token"
            ):
                # Propagate errors
                for error in self.token_validator.errors:
                    if error not in self.errors:
                        self.add_error(error)
                self.token_validator.clear_errors()
                valid = False

        # Custom validation logic
        if inputs.get("mode"):
            valid &= self.validate_mode(inputs["mode"])

        # Cross-field validation
        if inputs.get("source") and inputs.get("target"):
            valid &= self.validate_source_target(
                inputs["source"],
                inputs["target"]
            )

        return valid

    def get_required_inputs(self) -> list[str]:
        """Get list of required inputs.

        Returns:
            List of required input names
        """
        return ["api-token", "mode"]

    def validate_mode(self, mode: str) -> bool:
        """Validate operation mode.

        Args:
            mode: The mode value

        Returns:
            True if valid, False otherwise
        """
        valid_modes = ["development", "staging", "production"]

        if mode not in valid_modes:
            self.add_error(
                f"Invalid mode: {mode}. "
                f"Must be one of: {', '.join(valid_modes)}"
            )
            return False

        return True

    def validate_source_target(self, source: str, target: str) -> bool:
        """Validate source and target relationship.

        Args:
            source: Source value
            target: Target value

        Returns:
            True if valid, False otherwise
        """
        if source == target:
            self.add_error("Source and target cannot be the same")
            return False

        return True

Adding Convention Patterns

Pattern Priority

Patterns are checked in this order:

1. Exact match (highest priority)
2. Prefix match (token-*)
3. Suffix match (*-token)
4. Contains match (lowest priority)

Adding a New Pattern

# In validate-inputs/validators/conventions.py

# For automatic token validation of "api-key" inputs:
PATTERNS = {
    "exact": {
        "api-key": "token",  # Maps api-key to TokenValidator
    },
}

# For all inputs ending with "-secret":
PATTERNS = {
    "suffix": {
        "-secret": "security",  # Maps to SecurityValidator
    },
}

Writing Tests

Core Validator Tests

Create validate-inputs/tests/test_mytype.py:

"""Tests for MyTypeValidator."""

import pytest
from validators.mytype import MyTypeValidator


class TestMyTypeValidator:
    """Test MyTypeValidator functionality."""

    def setup_method(self):
        """Set up test fixtures."""
        self.validator = MyTypeValidator("test-action")

    def test_initialization(self):
        """Test validator initialization."""
        assert self.validator.action_type == "test-action"
        assert self.validator.errors == []

    def test_valid_mytype(self):
        """Test valid MyType values."""
        valid_cases = [
            "mytype-abc123",
            "mytype-test",
            "${{ secrets.MYTYPE }}",  # GitHub expression
            "",  # Empty allowed
        ]

        for value in valid_cases:
            self.validator.clear_errors()
            result = self.validator.validate_mytype(value, "test")
            assert result is True, f"Failed for: {value}"
            assert len(self.validator.errors) == 0

    def test_invalid_mytype(self):
        """Test invalid MyType values."""
        invalid_cases = [
            ("invalid", "Invalid MyType format"),
            ("mytype-", "Invalid MyType format"),
            ("MYTYPE-123", "Invalid MyType format"),  # Uppercase
        ]

        for value, expected_error in invalid_cases:
            self.validator.clear_errors()
            result = self.validator.validate_mytype(value, "test")
            assert result is False, f"Should fail for: {value}"
            assert any(
                expected_error in error
                for error in self.validator.errors
            )

    def test_validate_inputs(self):
        """Test full input validation."""
        inputs = {
            "mytype-field": "mytype-valid",
            "other-field": "ignored",
        }

        result = self.validator.validate_inputs(inputs)
        assert result is True
        assert len(self.validator.errors) == 0

Custom Validator Tests

Create my-action/test_custom_validator.py:

"""Tests for my-action CustomValidator."""

import sys
from pathlib import Path

# Add parent to path for imports
sys.path.insert(0, str(Path(__file__).parent.parent))

from my_action.CustomValidator import CustomValidator


def test_custom_validator():
    """Test custom validation logic."""
    validator = CustomValidator()

    # Test valid inputs
    inputs = {
        "api-token": "${{ secrets.GITHUB_TOKEN }}",
        "mode": "production",
        "source": "dev",
        "target": "prod",
    }

    assert validator.validate_inputs(inputs) is True
    assert len(validator.errors) == 0

    # Test invalid mode
    validator.clear_errors()
    inputs["mode"] = "invalid"

    assert validator.validate_inputs(inputs) is False
    assert "Invalid mode" in str(validator.errors)

Using Test Generator

Generate test scaffolding automatically:

# Generate missing tests
make generate-tests

# Preview what would be generated
make generate-tests-dry

# Test specific action
python3 validate-inputs/scripts/generate-tests.py --action my-action

Debugging

Enable Debug Output

import logging

# In your validator
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

class MyValidator(BaseValidator):
    def validate_mytype(self, value: str, field_name: str) -> bool:
        logger.debug(f"Validating {field_name}: {value}")
        # ... validation logic ...

Test Validator Directly

#!/usr/bin/env python3
"""Debug validator directly."""

from validators.mytype import MyTypeValidator

validator = MyTypeValidator("debug")
result = validator.validate_mytype("test-value", "field")

print(f"Valid: {result}")
print(f"Errors: {validator.errors}")

Check Convention Matching

from validators.conventions import ConventionBasedValidator

validator = ConventionBasedValidator("test")
mapper = validator.convention_mapper

# Check what validator would be used
validator_type = mapper.get_validator_type("my-field-name")
print(f"Would use: {validator_type}")

Common Patterns

Pattern 1: Composing Validators

class CustomValidator(BaseValidator):
    def __init__(self, action_type: str) -> None:
        super().__init__(action_type)
        # Compose multiple validators
        self.token_val = TokenValidator(action_type)
        self.version_val = VersionValidator(action_type)
        self.docker_val = DockerValidator(action_type)

Pattern 2: Error Propagation

def validate_inputs(self, inputs: dict[str, str]) -> bool:
    # Use sub-validator
    result = self.docker_val.validate_image_name(
        inputs["image"], "image"
    )

    if not result:
        # Propagate errors
        for error in self.docker_val.errors:
            if error not in self.errors:
                self.add_error(error)
        self.docker_val.clear_errors()
        return False

Pattern 3: GitHub Expression Support

def validate_field(self, value: str, field_name: str) -> bool:
    # Allow GitHub Actions expressions
    if self.is_github_expression(value):
        return True

    # Your validation logic
    # ...

Pattern 4: Optional vs Required

def validate_field(self, value: str, field_name: str) -> bool:
    # Allow empty for optional fields
    if not value or not value.strip():
        return True

    # Validate non-empty values
    # ...

Pattern 5: Security Checks

def validate_input(self, value: str, field_name: str) -> bool:
    # Always check for injection attempts
    if not self.validate_security_patterns(value, field_name):
        return False

    # Your validation logic
    # ...

Performance Tips

1. Cache Regex Patterns:

   class MyValidator(BaseValidator):
       # Compile once at class level
       PATTERN = re.compile(r"^mytype-[a-z0-9]+$")
   
       def validate_mytype(self, value: str, field_name: str) -> bool:
           if not self.PATTERN.match(value):
               # ...
   

2. Lazy Load Sub-Validators:

   @property
   def docker_validator(self):
       if not hasattr(self, "_docker_validator"):
           self._docker_validator = DockerValidator(self.action_type)
       return self._docker_validator
   

3. Early Returns:

   def validate_inputs(self, inputs: dict[str, str]) -> bool:
       # Check required inputs first
       if not self.validate_required_inputs(inputs):
           return False  # Exit early
   
       # Continue with other validations
       # ...
   

Checklist for New Validators

• Create validator class extending BaseValidator
• Implement validate_inputs method
• Add to __init__.py exports
• Add convention patterns if applicable
• Write comprehensive tests
• Test with GitHub expressions (${{ }})
• Test with empty/whitespace values
• Document validation rules
• Handle error propagation from sub-validators
• Run linting: make lint-python
• Run tests: make test-python
• Generate tests: make generate-tests

Getting Help

1. Check existing validators for similar patterns
2. Run tests to verify your implementation
3. Use debugging to trace validation flow
4. Review API documentation for method signatures
5. Check test files for usage examples

Next Steps

After creating your validator:

1. Update action rules: Run make update-validators
2. Test with real action: Use the validator with your GitHub Action
3. Document special rules: Add to action's README
4. Monitor for issues: Check GitHub Actions logs for validation errors