mirror of
https://github.com/ivuorinen/actions.git
synced 2026-01-26 03:23:59 +00:00
chore: add tests, update docs and actions (#299)
* docs: update documentation * feat: validate-inputs has it's own pyproject * security: mask DOCKERHUB_PASSWORD * chore: add tokens, checkout, recrete docs, integration tests * fix: add `statuses: write` permission to pr-lint
This commit is contained in:
GitHub
115
.serena/memories/development_standards.md
Normal file
115
.serena/memories/development_standards.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Development Standards & Workflows
|
||||
|
||||
## Quality Standards (ZERO TOLERANCE)
|
||||
|
||||
### Production Ready Criteria
|
||||
|
||||
- ALL tests pass (100% success rate)
|
||||
- ALL linting passes (zero issues)
|
||||
- ALL validation checks pass
|
||||
- NO warnings or errors
|
||||
|
||||
### Communication
|
||||
|
||||
- Direct, factual only
|
||||
- Never claim "production ready" until literally everything passes
|
||||
- No hype, buzzwords, or excessive enthusiasm
|
||||
|
||||
## Required Commands
|
||||
|
||||
### Development Cycle
|
||||
|
||||
```bash
|
||||
make all # Complete: docs, format, lint, test
|
||||
make dev # Format + lint (development)
|
||||
make lint # All linters (MUST pass 100%)
|
||||
make test # All tests (MUST pass 100%)
|
||||
make format # Auto-fix formatting
|
||||
```
|
||||
|
||||
### Task Completion Checklist
|
||||
|
||||
After ANY coding task:
|
||||
|
||||
- [ ] `make lint` - Fix all issues (blocking)
|
||||
- [ ] `make test` - Ensure 100% pass
|
||||
- [ ] EditorConfig compliance verified
|
||||
|
||||
### Validation System
|
||||
|
||||
```bash
|
||||
make update-validators # Generate validation rules
|
||||
make update-validators-dry # Preview changes
|
||||
make generate-tests # Create missing tests
|
||||
make generate-tests-dry # Preview test generation
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
### EditorConfig (BLOCKING ERRORS)
|
||||
|
||||
- **Indent**: 2 spaces (4 for Python, tabs for Makefile)
|
||||
- **Charset**: UTF-8
|
||||
- **Line Endings**: LF
|
||||
- **Max Line**: 200 chars (120 for Markdown)
|
||||
- **Final Newline**: Required
|
||||
- **Trailing Whitespace**: Trimmed
|
||||
|
||||
### Shell Scripts (REQUIRED)
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail # MANDATORY
|
||||
IFS=$' \t\n'
|
||||
trap cleanup EXIT
|
||||
trap 'echo "Error at line $LINENO" >&2' ERR
|
||||
# Always quote: "$variable", basename -- "$path"
|
||||
# Check tools: command -v jq >/dev/null 2>&1
|
||||
```
|
||||
|
||||
### Python (Ruff)
|
||||
|
||||
- **Line Length**: 100 chars
|
||||
- **Indent**: 4 spaces
|
||||
- **Quotes**: Double
|
||||
- **Docstrings**: Google style
|
||||
- **Type Hints**: Required
|
||||
|
||||
### YAML/Actions
|
||||
|
||||
- **Indent**: 2 spaces
|
||||
- **Local Actions**: `uses: ./action-name` (never `../` or `@main`)
|
||||
- **External Actions**: SHA-pinned (not `@main`/`@v1`)
|
||||
- **Step IDs**: Required when outputs referenced
|
||||
- **Permissions**: Minimal scope (contents: read default)
|
||||
- **Output Sanitization**: Use `printf`, never `echo` for `$GITHUB_OUTPUT`
|
||||
|
||||
## Security Requirements
|
||||
|
||||
1. **SHA Pinning**: All external actions use commit SHAs
|
||||
2. **Token Safety**: `${{ github.token }}`, never hardcoded
|
||||
3. **Input Validation**: All inputs validated via centralized system
|
||||
4. **Output Sanitization**: `printf '%s\n' "$value" >> $GITHUB_OUTPUT`
|
||||
5. **Injection Prevention**: Validate for `;`, `&&`, `|`, backticks
|
||||
6. **Tool Availability**: `command -v tool` checks before use
|
||||
7. **Variable Quoting**: Always `"$var"` in shell
|
||||
8. **No Secrets**: Never commit credentials/keys
|
||||
|
||||
## Never Do
|
||||
|
||||
- Never `git commit` (manual commits not allowed)
|
||||
- Never use `--no-verify` flags
|
||||
- Never modify linting config to make tests pass
|
||||
- Never assume linting issues are acceptable
|
||||
- Never skip testing after changes
|
||||
- Never create files unless absolutely necessary
|
||||
- Never nest `${{ }}` in quoted YAML strings (breaks hashFiles)
|
||||
|
||||
## Preferred Patterns
|
||||
|
||||
- Edit existing files over creating new ones
|
||||
- Use centralized validation for all input handling
|
||||
- Follow existing conventions in codebase
|
||||
- Actions use composition, not dependencies
|
||||
- Custom validators in action directories
|
||||
- Convention-based automatic detection
|
||||
101
.serena/memories/documentation_guide.md
Normal file
101
.serena/memories/documentation_guide.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Documentation Guide
|
||||
|
||||
## Documentation Locations
|
||||
|
||||
### Validation System Docs (`validate-inputs/docs/`)
|
||||
|
||||
Read when working with validators or validation logic:
|
||||
|
||||
**API.md** - Complete API reference
|
||||
|
||||
- BaseValidator methods and properties
|
||||
- Core validators (Boolean, Version, Token, Numeric, Docker, File, Network, Security, CodeQL)
|
||||
- Registry system usage
|
||||
- Custom validator patterns
|
||||
- Convention system
|
||||
|
||||
**DEVELOPER_GUIDE.md** - Creating new validators
|
||||
|
||||
- Quick start guide
|
||||
- Creating core validators (in validators/ directory)
|
||||
- Creating custom validators (in action directories)
|
||||
- Adding convention patterns
|
||||
- Writing tests, debugging, common patterns
|
||||
|
||||
**ACTION_MAINTAINER.md** - Using validation in actions
|
||||
|
||||
- How validation works (automatic integration)
|
||||
- Validation flow (input collection, validator selection, execution, error reporting)
|
||||
- Using automatic validation via conventions
|
||||
- Custom validation for complex scenarios
|
||||
- Testing validation, common scenarios, troubleshooting
|
||||
|
||||
**README_ARCHITECTURE.md** - System architecture
|
||||
|
||||
- Feature overview
|
||||
- Quick start examples
|
||||
- Architecture details
|
||||
- Modular validator structure
|
||||
- Convention-based detection
|
||||
- Custom validator support
|
||||
|
||||
### Testing Framework (`_tests/README.md`)
|
||||
|
||||
Read when writing or debugging tests:
|
||||
|
||||
- ShellSpec framework overview
|
||||
- Multi-level testing strategy (unit, integration, external usage)
|
||||
- Directory structure explanation
|
||||
- Test writing patterns
|
||||
- Running tests (`make test`, `make test-unit`, `make test-action ACTION=name`)
|
||||
- Coverage reporting
|
||||
- Mocking and fixtures
|
||||
- CI integration
|
||||
|
||||
### Docker Testing Tools (`_tools/docker-testing-tools/README.md`)
|
||||
|
||||
Read when working with CI or testing infrastructure:
|
||||
|
||||
- Pre-built Docker image with all testing tools
|
||||
- Pre-installed tools (ShellSpec, nektos/act, TruffleHog, actionlint, etc.)
|
||||
- Building locally (build.sh, test.sh)
|
||||
- Performance benefits (saves ~3 minutes per run)
|
||||
- Multi-stage build process
|
||||
- Usage in workflows
|
||||
|
||||
### Top-Level Documentation
|
||||
|
||||
**README.md** - Main project readme (auto-generated)
|
||||
|
||||
- Actions catalog
|
||||
- Usage examples
|
||||
- Quick reference
|
||||
|
||||
**SECURITY.md** - Security policy
|
||||
|
||||
- Reporting vulnerabilities
|
||||
- Security practices
|
||||
|
||||
**LICENSE.md** - MIT license
|
||||
|
||||
**CLAUDE.md** - Project instructions (covered in development_standards memory)
|
||||
|
||||
## When to Read What
|
||||
|
||||
**Starting new validator work**: Read `DEVELOPER_GUIDE.md`, then `API.md` for reference
|
||||
|
||||
**Using validation in action**: Read `ACTION_MAINTAINER.md`
|
||||
|
||||
**Understanding architecture**: Read `README_ARCHITECTURE.md`
|
||||
|
||||
**Writing tests**: Read `_tests/README.md`
|
||||
|
||||
**Setting up CI/testing**: Read `_tools/docker-testing-tools/README.md`
|
||||
|
||||
**API reference lookup**: Read `API.md` (has method tables, validator details)
|
||||
|
||||
## Documentation is Auto-Generated
|
||||
|
||||
- Action READMEs generated via `action-docs` (don't edit manually)
|
||||
- Validation system README auto-generated
|
||||
- Keep CLAUDE.md and docs/ files updated manually
|
||||
@@ -1,75 +0,0 @@
|
||||
# Linting Improvements - September 2025
|
||||
|
||||
## Summary
|
||||
|
||||
Successfully reduced linting issues from 213 to 99 in the modular validator architecture.
|
||||
|
||||
## Issues Fixed
|
||||
|
||||
### Critical Issues Resolved
|
||||
|
||||
1. **Print Statements** - All converted to proper logging with logger
|
||||
2. **F-string Logging** - Converted to lazy % formatting
|
||||
3. **Mutable Class Attributes** - Added `ClassVar` type annotations
|
||||
4. **Import Sorting** - Fixed and organized
|
||||
5. **File Path Operations** - Replaced os.path with Path
|
||||
6. **Exception Handling** - Improved specific exception catching
|
||||
|
||||
## Code Changes Made
|
||||
|
||||
### Logging Improvements
|
||||
|
||||
```python
|
||||
# Before
|
||||
print(f"::error::{error}")
|
||||
|
||||
# After
|
||||
logger.error("::error::%s", error)
|
||||
```
|
||||
|
||||
### Class Attributes
|
||||
|
||||
```python
|
||||
# Before
|
||||
SUPPORTED_LANGUAGES = {...}
|
||||
|
||||
# After
|
||||
SUPPORTED_LANGUAGES: ClassVar[set[str]] = {...}
|
||||
```
|
||||
|
||||
### Path Operations
|
||||
|
||||
```python
|
||||
# Before
|
||||
if os.path.exists(self.temp_output.name):
|
||||
|
||||
# After
|
||||
if Path(self.temp_output.name).exists():
|
||||
```
|
||||
|
||||
## Remaining Issues (99 total)
|
||||
|
||||
### Acceptable Issues
|
||||
|
||||
- **39 PLC0415** - Import-outside-top-level (intentional in tests for isolation)
|
||||
- **27 PLR2004** - Magic value comparisons (domain-specific constants)
|
||||
- **9 PLR0911** - Too many return statements (complex validation logic)
|
||||
- **7 BLE001** - Blind except (appropriate for fallback scenarios)
|
||||
- **7 TRY300** - Try-consider-else (current pattern is clearer)
|
||||
- **3 S105** - Hardcoded password strings (test data)
|
||||
- **3 SIM115** - Context managers (NamedTemporaryFile usage)
|
||||
- **1 C901** - Complexity (validator.main function)
|
||||
- **1 FIX002** - TODO comment (tracked in issue)
|
||||
- **1 S110** - Try-except-pass (appropriate fallback)
|
||||
- **1 S603** - Subprocess call (controlled input in tests)
|
||||
|
||||
## Test Status
|
||||
|
||||
- 286 tests passing
|
||||
- 17 tests failing (output format changes)
|
||||
- 94.4% pass rate
|
||||
|
||||
## Conclusion
|
||||
|
||||
All critical linting issues have been resolved. The remaining 99 issues are mostly style preferences or intentional patterns that are acceptable for this codebase.
|
||||
The code quality has significantly improved while maintaining functionality.
|
||||
@@ -1,345 +0,0 @@
|
||||
# Modular Validator Architecture - Complete Documentation
|
||||
|
||||
## Current Status: PRODUCTION READY ✅
|
||||
|
||||
**Last Updated**: 2025-09-16
|
||||
**Branch**: feat/upgrades-and-restructuring
|
||||
**Phase Completed**: 1-5 of 7 (Test Generation System Implemented)
|
||||
**Test Status**: 100% pass rate (303/303 tests passing)
|
||||
**Linting**: 0 issues
|
||||
**Quality**: Production ready, zero defects
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
Successfully transformed monolithic `validator.py` into a modular, extensible validation system for GitHub Actions inputs.
|
||||
The architecture now provides specialized validators, convention-based auto-detection, support for custom validators, and an intelligent test generation system.
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Base Framework
|
||||
|
||||
- **BaseValidator** (`validators/base.py`): Abstract base class defining validator interface
|
||||
- **ValidatorRegistry** (`validators/registry.py`): Dynamic validator discovery and management
|
||||
- **ConventionMapper** (`validators/conventions.py`): Automatic validation based on naming patterns
|
||||
|
||||
### 2. Specialized Validator Modules (9 Total)
|
||||
|
||||
| Module | Purpose | Status |
|
||||
| ------------------------ | --------------------------------- | ----------- |
|
||||
| `validators/token.py` | GitHub, NPM, PyPI, Docker tokens | ✅ Complete |
|
||||
| `validators/version.py` | SemVer, CalVer, language versions | ✅ Complete |
|
||||
| `validators/boolean.py` | Boolean value validation | ✅ Complete |
|
||||
| `validators/numeric.py` | Numeric ranges and constraints | ✅ Complete |
|
||||
| `validators/docker.py` | Docker images, tags, platforms | ✅ Complete |
|
||||
| `validators/file.py` | File paths, extensions, security | ✅ Complete |
|
||||
| `validators/network.py` | URLs, emails, IPs, ports | ✅ Complete |
|
||||
| `validators/security.py` | Injection detection, secrets | ✅ Complete |
|
||||
| `validators/codeql.py` | CodeQL queries, languages, config | ✅ Complete |
|
||||
|
||||
### 3. Custom Validators (4 Implemented)
|
||||
|
||||
| Action | Custom Validator | Features |
|
||||
| ----------------- | ---------------- | ------------------------------------ |
|
||||
| `sync-labels` | ✅ Implemented | YAML file validation, GitHub token |
|
||||
| `docker-build` | ✅ Implemented | Complex build args, platforms, cache |
|
||||
| `codeql-analysis` | ✅ Implemented | Language support, query validation |
|
||||
| `docker-publish` | ✅ Implemented | Registry validation, credentials |
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### ✅ Phase 1: Core Infrastructure (COMPLETED)
|
||||
|
||||
- Created modular directory structure
|
||||
- Implemented BaseValidator abstract class
|
||||
- Built ValidatorRegistry with auto-discovery
|
||||
- Established testing framework
|
||||
|
||||
### ✅ Phase 2: Specialized Validators (COMPLETED)
|
||||
|
||||
- Extracted validation logic into 9 specialized modules
|
||||
- Created comprehensive test coverage
|
||||
- Achieved full pytest compatibility
|
||||
- Fixed all method signatures and interfaces
|
||||
|
||||
### ✅ Phase 3: Convention Mapper (COMPLETED)
|
||||
|
||||
- Implemented priority-based pattern matching (100+ patterns)
|
||||
- Created ConventionBasedValidator for automatic validation
|
||||
- Added YAML-based convention override support
|
||||
- Integrated with ValidatorRegistry
|
||||
|
||||
### ✅ Phase 4: Custom Validator Support (COMPLETED)
|
||||
|
||||
- Implemented custom validator discovery in registry
|
||||
- Created 4 custom validators for complex actions
|
||||
- Fixed error propagation between parent/child validators
|
||||
- Added full GitHub expression (`${{ }}`) support
|
||||
- All custom validator tests passing (6/6)
|
||||
|
||||
### ✅ Phase 5: Test Generation System (COMPLETED)
|
||||
|
||||
- Implemented `generate-tests.py` script with intelligent pattern detection
|
||||
- Created test templates for different validator types
|
||||
- Added skip-existing-tests logic to prevent overwrites
|
||||
- Integrated with Makefile (`make generate-tests`, `make generate-tests-dry`)
|
||||
- Created comprehensive tests for the generator itself (11 tests passing)
|
||||
- Supports both ShellSpec and pytest test generation
|
||||
- Handles custom validators in action directories
|
||||
|
||||
#### Test Generation Features
|
||||
|
||||
- **Intelligent Input Detection**: Recognizes patterns like `token`, `version`, `path`, `url`, `email`, `dry-run`, etc.
|
||||
- **Context-Aware Test Cases**: Generates appropriate test cases based on input types
|
||||
- **GitHub Expression Support**: Includes tests for `${{ }}` expressions
|
||||
- **Template System**: Different templates for version, token, boolean, numeric, file, network, docker, and security validators
|
||||
- **Non-Destructive**: Never overwrites existing test files
|
||||
- **Dry Run Mode**: Preview what would be generated without creating files
|
||||
- **Comprehensive Coverage**: Generates ShellSpec tests for actions, pytest tests for validators, and tests for custom validators
|
||||
|
||||
#### Test Generation Commands
|
||||
|
||||
```bash
|
||||
make generate-tests # Generate missing tests
|
||||
make generate-tests-dry # Preview what would be generated
|
||||
make test-generate-tests # Test the generator itself
|
||||
```
|
||||
|
||||
### ⏳ Phase 6: Integration and Migration (NOT STARTED)
|
||||
|
||||
- Update YAML rules to new schema format
|
||||
- Migrate remaining actions to custom validators
|
||||
- Update rule generation scripts
|
||||
|
||||
### ⏳ Phase 7: Documentation and Tooling (NOT STARTED)
|
||||
|
||||
- Create validator development guide
|
||||
- Add CLI tools for validator testing
|
||||
- Update all documentation
|
||||
|
||||
## Convention-Based Detection
|
||||
|
||||
The ConventionMapper provides automatic validator selection based on input naming patterns:
|
||||
|
||||
```text
|
||||
# Priority levels (higher = more specific)
|
||||
100: Exact matches (e.g., "dry-run" → boolean)
|
||||
95: Language-specific versions (e.g., "-python-version" → python_version)
|
||||
90: Generic suffixes (e.g., "-token" → token)
|
||||
85: Contains patterns (e.g., contains "email" → email)
|
||||
80: Prefix patterns (e.g., "is-" → boolean)
|
||||
```
|
||||
|
||||
## Key Technical Achievements
|
||||
|
||||
### Error Propagation Pattern
|
||||
|
||||
```python
|
||||
# Proper error propagation from child to parent validators
|
||||
result = self.child_validator.validate_something(value)
|
||||
for error in self.child_validator.errors:
|
||||
if error not in self.errors:
|
||||
self.add_error(error)
|
||||
self.child_validator.clear_errors()
|
||||
return result
|
||||
```
|
||||
|
||||
### GitHub Expression Support
|
||||
|
||||
All validators properly handle GitHub Actions expressions:
|
||||
|
||||
```python
|
||||
# Allow GitHub Actions expressions
|
||||
if self.is_github_expression(value):
|
||||
return True
|
||||
```
|
||||
|
||||
### Platform Validation
|
||||
|
||||
Docker platform validation accepts full platform strings:
|
||||
|
||||
- `linux/amd64`, `linux/arm64`, `linux/arm/v7`
|
||||
- `windows/amd64` (where applicable)
|
||||
- `darwin/arm64` (where applicable)
|
||||
|
||||
## Testing Infrastructure
|
||||
|
||||
### Test Statistics
|
||||
|
||||
- **Total Tests**: 303 (including 11 test generator tests)
|
||||
- **Passing**: 303 (100%)
|
||||
- **Coverage by Module**: All modules have dedicated test files
|
||||
- **Custom Validators**: 6 comprehensive tests
|
||||
- **Test Generator**: 11 tests for the generation system
|
||||
|
||||
### Test Files
|
||||
|
||||
```text
|
||||
validate-inputs/tests/
|
||||
├── test_base.py ✅
|
||||
├── test_registry.py ✅
|
||||
├── test_convention_mapper.py ✅
|
||||
├── test_boolean_validator.py ✅
|
||||
├── test_codeql_validator.py ✅
|
||||
├── test_docker_validator.py ✅
|
||||
├── test_file_validator.py ✅
|
||||
├── test_network_validator.py ✅
|
||||
├── test_numeric_validator.py ✅
|
||||
├── test_security_validator.py ✅
|
||||
├── test_token_validator.py ✅
|
||||
├── test_version_validator.py ✅
|
||||
├── test_custom_validators.py ✅ (6 tests)
|
||||
├── test_integration.py ✅
|
||||
├── test_validator.py ✅
|
||||
└── test_generate_tests.py ✅ (11 tests)
|
||||
```
|
||||
|
||||
### Test Generation System
|
||||
|
||||
```text
|
||||
validate-inputs/scripts/
|
||||
└── generate-tests.py ✅ Intelligent test generator
|
||||
```
|
||||
|
||||
## Production Readiness Criteria
|
||||
|
||||
✅ **ALL CRITERIA MET**:
|
||||
|
||||
- Zero failing tests (303/303 passing)
|
||||
- Zero linting issues
|
||||
- Zero type checking issues
|
||||
- Full backward compatibility maintained
|
||||
- Comprehensive error handling
|
||||
- Security patterns validated
|
||||
- Performance optimized (lazy loading, caching)
|
||||
- Custom validator support proven
|
||||
- GitHub expression handling complete
|
||||
- Test generation system operational
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Validation
|
||||
|
||||
```python
|
||||
from validators.registry import ValidatorRegistry
|
||||
|
||||
registry = ValidatorRegistry()
|
||||
validator = registry.get_validator("docker-build")
|
||||
result = validator.validate_inputs({
|
||||
"context": ".",
|
||||
"dockerfile": "Dockerfile",
|
||||
"platforms": "linux/amd64,linux/arm64"
|
||||
})
|
||||
```
|
||||
|
||||
### Custom Validator
|
||||
|
||||
```python
|
||||
# Automatically loads docker-build/CustomValidator.py
|
||||
validator = registry.get_validator("docker-build")
|
||||
# Uses specialized validation logic for docker-build action
|
||||
```
|
||||
|
||||
### Test Generation
|
||||
|
||||
```bash
|
||||
# Generate missing tests for all actions and validators
|
||||
python3 validate-inputs/scripts/generate-tests.py
|
||||
|
||||
# Preview what would be generated (dry run)
|
||||
python3 validate-inputs/scripts/generate-tests.py --dry-run --verbose
|
||||
|
||||
# Generated test example
|
||||
#!/usr/bin/env bash
|
||||
Describe 'Action Name Input Validation'
|
||||
Context 'Required inputs validation'
|
||||
It 'should fail when required inputs are missing'
|
||||
When run validate_inputs 'action-name'
|
||||
The status should be failure
|
||||
End
|
||||
End
|
||||
End
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```text
|
||||
validate-inputs/
|
||||
├── validator.py # Main entry point
|
||||
├── validators/
|
||||
│ ├── __init__.py
|
||||
│ ├── base.py # BaseValidator abstract class
|
||||
│ ├── registry.py # ValidatorRegistry
|
||||
│ ├── conventions.py # ConventionBasedValidator
|
||||
│ ├── [9 specialized validators]
|
||||
│ └── ...
|
||||
├── rules/ # YAML validation rules
|
||||
├── tests/ # Comprehensive test suite
|
||||
│ ├── [validator tests]
|
||||
│ └── test_generate_tests.py # Test generator tests
|
||||
└── scripts/
|
||||
├── update-validators.py # Rule generator
|
||||
└── generate-tests.py # Test generator ✅
|
||||
|
||||
# Custom validators in action directories
|
||||
sync-labels/CustomValidator.py ✅
|
||||
docker-build/CustomValidator.py ✅
|
||||
codeql-analysis/CustomValidator.py ✅
|
||||
docker-publish/CustomValidator.py ✅
|
||||
```
|
||||
|
||||
## Benefits Achieved
|
||||
|
||||
### 1. Modularity
|
||||
|
||||
- Each validator is self-contained
|
||||
- Clear separation of concerns
|
||||
- Easy to test individually
|
||||
|
||||
### 2. Extensibility
|
||||
|
||||
- New validators easily added
|
||||
- Custom validators for complex actions
|
||||
- Convention-based auto-detection
|
||||
- Automatic test generation
|
||||
|
||||
### 3. Maintainability
|
||||
|
||||
- Individual test files per validator
|
||||
- Consistent interfaces
|
||||
- Clear error messages
|
||||
- Tests generated with consistent patterns
|
||||
|
||||
### 4. Performance
|
||||
|
||||
- Lazy loading of validators
|
||||
- Efficient pattern matching
|
||||
- Minimal overhead
|
||||
- Fast test generation
|
||||
|
||||
### 5. Developer Experience
|
||||
|
||||
- Automatic test scaffolding
|
||||
- Intelligent pattern detection
|
||||
- Non-destructive generation
|
||||
- Comprehensive test coverage
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Phase 6**: Integration and Migration
|
||||
- Update YAML rules to new schema format
|
||||
- Migrate more actions to custom validators
|
||||
|
||||
2. **Phase 7**: Documentation and Tooling
|
||||
- Create comprehensive validator development guide
|
||||
- Add CLI tools for validator testing
|
||||
|
||||
3. **Optional Enhancements**:
|
||||
- Create more custom validators (github-release, npm-publish)
|
||||
- Enhance test generation templates
|
||||
- Add performance benchmarks
|
||||
|
||||
## Summary
|
||||
|
||||
The modular validator architecture with test generation is **complete and production-ready**. Phases 1-5 are done, providing a robust, extensible,
|
||||
and well-tested validation system for GitHub Actions. The test generation system ensures consistent test coverage and reduces manual test writing effort.
|
||||
The system maintains 100% test coverage with zero defects, follows SOLID principles, and maintains full backward compatibility.
|
||||
@@ -1,200 +0,0 @@
|
||||
# Modular Validator Architecture - COMPLETED
|
||||
|
||||
## Overview
|
||||
|
||||
Successfully implemented a comprehensive modular validation system for GitHub Actions, replacing the monolithic validator.py with a flexible, extensible architecture.
|
||||
|
||||
## Implementation Status: COMPLETED (September 2025)
|
||||
|
||||
All 7 phases completed with 100% test pass rate and zero linting issues.
|
||||
|
||||
## Architecture Components
|
||||
|
||||
### Core System
|
||||
|
||||
1. **BaseValidator** (`validators/base.py`)
|
||||
- Abstract base class defining validation interface
|
||||
- Standard methods: validate_inputs, add_error, clear_errors
|
||||
- Extensible for custom validators
|
||||
|
||||
2. **ValidatorRegistry** (`validators/registry.py`)
|
||||
- Dynamic validator discovery and loading
|
||||
- Custom validator support via action-specific `<action-name>/CustomValidator.py` files
|
||||
- Searches project root for `<action-dir>/CustomValidator.py` (e.g., `docker-build/CustomValidator.py`)
|
||||
- Fallback to convention-based validation when no custom validator exists
|
||||
- Added get_validator_by_type method for direct type access
|
||||
|
||||
3. **ConventionBasedValidator** (`validators/conventions.py`)
|
||||
- Pattern-based automatic validation
|
||||
- Detects validation needs from input names
|
||||
- Delegates to specific validators based on conventions
|
||||
|
||||
4. **ConventionMapper** (`validators/convention_mapper.py`)
|
||||
- Maps input patterns to validator types
|
||||
- Supports exact, prefix, suffix, and contains patterns
|
||||
- Efficient pattern matching with caching
|
||||
|
||||
### Specialized Validators
|
||||
|
||||
- **BooleanValidator**: Boolean values (true/false)
|
||||
- **VersionValidator**: SemVer, CalVer, flexible versioning
|
||||
- **TokenValidator**: GitHub tokens, API keys
|
||||
- **NumericValidator**: Integer/float ranges
|
||||
- **FileValidator**: File/directory paths
|
||||
- **NetworkValidator**: URLs, emails, hostnames
|
||||
- **DockerValidator**: Images, tags, platforms
|
||||
- **SecurityValidator**: Injection protection, security patterns
|
||||
- **CodeQLValidator**: Languages, queries, config
|
||||
|
||||
### Custom Validators
|
||||
|
||||
- Action-specific validation via `<action-name>/CustomValidator.py` files
|
||||
- Located in each action's directory (e.g., `docker-build/CustomValidator.py`, `npm-publish/CustomValidator.py`)
|
||||
- Extends ConventionBasedValidator or BaseValidator
|
||||
- Registry discovers custom validators by searching action directories in project root
|
||||
- Examples: docker-build, sync-labels, npm-publish, php-laravel-phpunit, validate-inputs
|
||||
|
||||
## Testing Infrastructure
|
||||
|
||||
### Test Generation System
|
||||
|
||||
- **generate-tests.py**: Non-destructive test generation
|
||||
- Preserves existing tests
|
||||
- Generates ShellSpec and pytest tests
|
||||
- Pattern-based test case creation
|
||||
- 900+ lines of intelligent test scaffolding
|
||||
|
||||
### Test Coverage
|
||||
|
||||
- 303 total tests passing
|
||||
- ShellSpec for action validation
|
||||
- pytest for Python validators
|
||||
- Integration tests for end-to-end validation
|
||||
- Performance benchmarks available
|
||||
|
||||
## Documentation & Tools
|
||||
|
||||
### Documentation
|
||||
|
||||
- **API.md**: Complete API reference
|
||||
- **DEVELOPER_GUIDE.md**: Adding new validators
|
||||
- **ACTION_MAINTAINER.md**: Using validation system
|
||||
- **README_ARCHITECTURE.md**: System overview
|
||||
|
||||
### Debug & Performance Tools
|
||||
|
||||
- **debug-validator.py**: Interactive debugging
|
||||
- **benchmark-validator.py**: Performance profiling
|
||||
- **update-validators.py**: Rule generation
|
||||
|
||||
## Code Quality
|
||||
|
||||
### Standards Achieved
|
||||
|
||||
- ✅ Zero linting issues (ruff, pyright)
|
||||
- ✅ 100% test pass rate (303 tests)
|
||||
- ✅ Full backward compatibility
|
||||
- ✅ Type hints throughout
|
||||
- ✅ Comprehensive documentation
|
||||
- ✅ EditorConfig compliance
|
||||
|
||||
### Fixed Issues
|
||||
|
||||
- Import sorting and organization
|
||||
- F-string logging converted to lazy format
|
||||
- Boolean arguments made keyword-only
|
||||
- Type annotations using proper types
|
||||
- Private member access via public methods
|
||||
- Exception handling improvements
|
||||
- Added missing registry methods
|
||||
|
||||
## Integration
|
||||
|
||||
### Main Validator Integration
|
||||
|
||||
- validator.py uses ValidatorRegistry
|
||||
- Transparent migration from old system
|
||||
- All existing actions work unchanged
|
||||
- Custom validators take precedence
|
||||
|
||||
### GitHub Expression Support
|
||||
|
||||
- Proper handling of ${{ }} expressions
|
||||
- Expression validation in appropriate contexts
|
||||
- Security-aware expression checking
|
||||
|
||||
## File Structure
|
||||
|
||||
```text
|
||||
validate-inputs/
|
||||
├── validators/
|
||||
│ ├── __init__.py
|
||||
│ ├── base.py # Abstract base
|
||||
│ ├── registry.py # Discovery & loading
|
||||
│ ├── conventions.py # Pattern-based
|
||||
│ ├── convention_mapper.py # Pattern mapping
|
||||
│ ├── boolean.py # Specialized validators...
|
||||
│ ├── version.py
|
||||
│ └── ...
|
||||
├── rules/ # Auto-generated YAML
|
||||
├── tests/ # pytest tests
|
||||
├── scripts/
|
||||
│ ├── generate-tests.py # Test generation
|
||||
│ ├── debug-validator.py # Debugging
|
||||
│ ├── benchmark-validator.py # Performance
|
||||
│ └── update-validators.py # Rule generation
|
||||
├── docs/ # Documentation
|
||||
├── CustomValidator.py # Custom validator for validate-inputs action
|
||||
└── validator.py # Main entry point
|
||||
|
||||
# Custom validators in action directories (examples):
|
||||
docker-build/CustomValidator.py
|
||||
npm-publish/CustomValidator.py
|
||||
php-laravel-phpunit/CustomValidator.py
|
||||
version-validator/CustomValidator.py
|
||||
```
|
||||
|
||||
## Key Achievements
|
||||
|
||||
1. **Modular Architecture**: Clean separation of concerns
|
||||
2. **Convention-Based**: Automatic validation from naming patterns
|
||||
3. **Extensible**: Easy to add new validators
|
||||
4. **Backward Compatible**: No breaking changes
|
||||
5. **Well Tested**: Comprehensive test coverage
|
||||
6. **Documented**: Complete API and guides
|
||||
7. **Production Ready**: Zero defects, all quality gates passed
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Custom Validator
|
||||
|
||||
```python
|
||||
# docker-build/CustomValidator.py
|
||||
from validate-inputs.validators.conventions import ConventionBasedValidator
|
||||
from validate-inputs.validators.docker import DockerValidator
|
||||
|
||||
class CustomValidator(ConventionBasedValidator):
|
||||
def __init__(self, action_type: str):
|
||||
super().__init__(action_type)
|
||||
self.docker_validator = DockerValidator(action_type)
|
||||
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
# Custom validation logic
|
||||
if not self.validate_required_inputs(inputs, ["context"]):
|
||||
return False
|
||||
return super().validate_inputs(inputs)
|
||||
```
|
||||
|
||||
### Debug Usage
|
||||
|
||||
```bash
|
||||
# Debug an action
|
||||
python validate-inputs/scripts/debug-validator.py docker-build --inputs '{"context": ".", "platforms": "linux/amd64,linux/arm64"}'
|
||||
|
||||
# Benchmark performance
|
||||
python validate-inputs/scripts/benchmark-validator.py --action docker-build --iterations 1000
|
||||
```
|
||||
|
||||
## Migration Complete
|
||||
|
||||
The modular validator architecture is fully implemented, tested, documented, and integrated. All quality standards met with zero defects.
|
||||
@@ -1,199 +0,0 @@
|
||||
# Project Overview - GitHub Actions Monorepo
|
||||
|
||||
## Purpose
|
||||
|
||||
This repository contains a collection of reusable GitHub Actions designed to streamline CI/CD processes and ensure code quality.
|
||||
Each action is fully self-contained and can be used independently in any GitHub repository.
|
||||
|
||||
## Repository Information
|
||||
|
||||
- **Branch**: feat/upgrades-and-restructuring
|
||||
- **Location**: /Users/ivuorinen/Code/ivuorinen/actions
|
||||
- **External Usage**: `ivuorinen/actions/action-name@main`
|
||||
- **Last Updated**: January 2025
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Production-Ready Actions** covering setup, linting, building, testing, and deployment
|
||||
- **Self-Contained Design** - each action works independently without dependencies
|
||||
- **Modular Validator Architecture** - specialized validators with convention-based auto-detection
|
||||
- **Custom Validator Support** - complex actions have dedicated validation logic
|
||||
- **Test Generation System** - automatic test scaffolding with intelligent pattern detection
|
||||
- **Multi-Language Support** including Node.js, PHP, Python, Go, C#, Docker, and more
|
||||
- **Comprehensive Testing** with dual framework (ShellSpec + pytest)
|
||||
- **Zero Defect Policy** - 100% test pass rate, zero linting issues required
|
||||
|
||||
## Architecture Highlights
|
||||
|
||||
### Directory Structure
|
||||
|
||||
- **Flat Action Layout**: Each action in its own directory with `action.yml`
|
||||
- **Centralized Validation**: `validate-inputs/` with modular validator system
|
||||
- **Custom Validators**: Action-specific validators (e.g., `docker-build/CustomValidator.py`)
|
||||
- **Testing Infrastructure**: `_tests/` for ShellSpec, `validate-inputs/tests/` for pytest
|
||||
- **Build Tools**: `_tools/` for helper scripts and development utilities
|
||||
- **Test Generation**: `validate-inputs/scripts/generate-tests.py` for automatic test creation
|
||||
|
||||
### Validation System (Modular Architecture)
|
||||
|
||||
```text
|
||||
validate-inputs/
|
||||
├── validator.py # Main entry point
|
||||
├── validators/
|
||||
│ ├── base.py # Abstract base class
|
||||
│ ├── registry.py # Dynamic validator discovery
|
||||
│ ├── conventions.py # Convention-based auto-detection
|
||||
│ └── [9 specialized modules]
|
||||
├── scripts/
|
||||
│ ├── update-validators.py # Auto-generates validation rules
|
||||
│ └── generate-tests.py # Non-destructive test generation
|
||||
└── tests/ # Comprehensive test suite
|
||||
```
|
||||
|
||||
### Testing Framework
|
||||
|
||||
- **ShellSpec**: For testing shell scripts and GitHub Actions
|
||||
- **pytest**: For Python validation system (303 tests, 100% passing)
|
||||
- **Test Generator**: Automatic test scaffolding for new actions/validators
|
||||
- **Coverage**: Full test coverage for all validators
|
||||
|
||||
## Action Categories
|
||||
|
||||
**Total: 43 actions** across 8 categories
|
||||
|
||||
### Setup Actions (7)
|
||||
|
||||
- `node-setup`, `set-git-config`, `php-version-detect`, `python-version-detect`,
|
||||
- `python-version-detect-v2`, `go-version-detect`, `dotnet-version-detect`
|
||||
|
||||
### Linting Actions (13)
|
||||
|
||||
- `ansible-lint-fix`, `biome-check`, `biome-fix`, `csharp-lint-check`
|
||||
- `eslint-check`, `eslint-fix`, `go-lint`, `pr-lint`, `pre-commit`
|
||||
- `prettier-check`, `prettier-fix`, `python-lint-fix`, `terraform-lint-fix`
|
||||
|
||||
### Build Actions (3)
|
||||
|
||||
- `csharp-build`, `go-build`, `docker-build`
|
||||
|
||||
### Publishing Actions (5)
|
||||
|
||||
- `npm-publish`, `docker-publish`, `docker-publish-gh`, `docker-publish-hub`, `csharp-publish`
|
||||
|
||||
### Testing Actions (3)
|
||||
|
||||
- `php-tests`, `php-laravel-phpunit`, `php-composer`
|
||||
|
||||
### Repository (9)
|
||||
|
||||
- `github-release`, `release-monthly`, `sync-labels`, `stale`
|
||||
- `compress-images`, `common-cache`, `common-file-check`, `common-retry`
|
||||
- `codeql-analysis` (security analysis)
|
||||
|
||||
### Utilities (2)
|
||||
|
||||
- `version-file-parser`, `version-validator`
|
||||
|
||||
### Validation (1)
|
||||
|
||||
- `validate-inputs` (centralized input validation system)
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Core Commands
|
||||
|
||||
```bash
|
||||
make all # Generate docs, format, lint, test
|
||||
make dev # Format then lint
|
||||
make lint # Run all linters
|
||||
make test # Run all tests
|
||||
make update-validators # Update validation rules
|
||||
make generate-tests # Generate missing tests (non-destructive)
|
||||
make generate-tests-dry # Preview test generation
|
||||
```
|
||||
|
||||
### Quality Standards
|
||||
|
||||
- **ZERO TOLERANCE**: No failing tests, no linting issues
|
||||
- **Production Ready**: Only when ALL checks pass
|
||||
- **Convention Priority**: EditorConfig rules are blocking
|
||||
- **Security First**: No secrets, tokens, or sensitive data in code
|
||||
|
||||
## Recent Accomplishments (January 2025)
|
||||
|
||||
### Phase 1-4: Modular Validator Architecture ✅
|
||||
|
||||
- Transformed monolithic validator into 11 specialized modules
|
||||
- Implemented convention-based auto-detection (100+ patterns)
|
||||
- Created 3 custom validators for complex actions
|
||||
- Achieved 100% test pass rate (292/292 tests)
|
||||
- Zero linting issues across all code
|
||||
|
||||
### Phase 5: Test Generation System ✅
|
||||
|
||||
- Created non-destructive test generation (preserves existing tests)
|
||||
- Intelligent pattern detection for input types
|
||||
- Template-based scaffolding for different validator types
|
||||
- ShellSpec test generation for GitHub Actions
|
||||
- pytest test generation for validators
|
||||
- Custom validator test support
|
||||
- 11 comprehensive tests for the generator itself
|
||||
- Makefile integration with three new commands
|
||||
|
||||
### Custom Validators Implemented
|
||||
|
||||
1. `docker-build` - Complex build args, platforms, cache validation
|
||||
2. `codeql-analysis` - Language support, query validation
|
||||
3. `docker-publish` - Registry, credentials, platform validation
|
||||
|
||||
### Technical Improvements
|
||||
|
||||
- Full GitHub expression support (`${{ }}`)
|
||||
- Error propagation between parent/child validators
|
||||
- Platform-specific validation (Docker architectures)
|
||||
- Registry validation (Docker Hub, GHCR, etc.)
|
||||
- Security pattern detection and injection prevention
|
||||
- Non-destructive test generation system
|
||||
- Template-based test scaffolding
|
||||
|
||||
## Project Status
|
||||
|
||||
**Phases Completed**:
|
||||
|
||||
- ✅ Phase 1: Base Architecture (100% complete)
|
||||
- ✅ Phase 2: Core Validators (100% complete)
|
||||
- ✅ Phase 3: Registry System (100% complete)
|
||||
- ✅ Phase 4: Custom Validators (100% complete)
|
||||
- ✅ Phase 5: Test Generation (100% complete)
|
||||
- ⏳ Phase 6: Integration and Migration (in progress)
|
||||
- ⏳ Phase 7: Documentation and Tooling (not started)
|
||||
|
||||
**Quality Metrics**:
|
||||
|
||||
- ✅ 100% test pass rate (303 total tests)
|
||||
- ✅ Zero linting issues
|
||||
- ✅ Modular, extensible architecture
|
||||
- ✅ Custom validator support
|
||||
- ✅ Convention-based auto-detection
|
||||
- ✅ Full backward compatibility
|
||||
- ✅ Comprehensive error handling
|
||||
- ✅ Security validations
|
||||
- ✅ Test generation system
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Complete Phase 6: Integration and Migration
|
||||
- Integrate modular validators with main validator.py
|
||||
- Ensure full backward compatibility
|
||||
- Test all 50+ actions with integrated system
|
||||
2. Phase 7: Documentation and Tooling
|
||||
3. Performance optimization
|
||||
4. Production deployment
|
||||
|
||||
## IDE Configuration Note
|
||||
|
||||
For Pyright/Pylance import resolution in IDEs like Zed, VSCode:
|
||||
|
||||
- The project uses relative imports within validate-inputs
|
||||
- Python path includes validate-inputs directory
|
||||
- Tests use sys.path manipulation for imports
|
||||
@@ -1,171 +0,0 @@
|
||||
# Project Structure and Architecture
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```text
|
||||
/Users/ivuorinen/Code/ivuorinen/actions/
|
||||
├── Action Directories/ # Each action is self-contained
|
||||
│ ├── action.yml # Action definition
|
||||
│ ├── README.md # Auto-generated documentation
|
||||
│ └── CustomValidator.py # Optional custom validator
|
||||
├── validate-inputs/ # Centralized validation system
|
||||
│ ├── validator.py # Main entry point
|
||||
│ ├── validators/ # Modular validator architecture
|
||||
│ │ ├── base.py # Abstract base class
|
||||
│ │ ├── registry.py # Dynamic validator discovery
|
||||
│ │ ├── conventions.py # Convention-based detection
|
||||
│ │ ├── boolean.py # Boolean validation
|
||||
│ │ ├── codeql.py # CodeQL-specific validation
|
||||
│ │ ├── docker.py # Docker validation
|
||||
│ │ ├── file.py # File path validation
|
||||
│ │ ├── network.py # Network/URL validation
|
||||
│ │ ├── numeric.py # Numeric validation
|
||||
│ │ ├── security.py # Security pattern detection
|
||||
│ │ ├── token.py # Token validation
|
||||
│ │ └── version.py # Version validation
|
||||
│ ├── rules/ # Auto-generated YAML rules
|
||||
│ ├── scripts/ # Rule generation utilities
|
||||
│ └── tests/ # Comprehensive pytest suite (292 tests)
|
||||
├── _tests/ # ShellSpec testing framework
|
||||
│ ├── unit/ # Unit tests for actions
|
||||
│ ├── framework/ # Testing utilities
|
||||
│ └── shared/ # Shared test components
|
||||
├── _tools/ # Development utilities
|
||||
│ ├── docker-testing-tools/ # Docker test environment
|
||||
│ └── fix-local-action-refs.py # Action reference fixer
|
||||
├── .github/ # GitHub configuration
|
||||
│ └── workflows/ # CI/CD workflows
|
||||
├── .serena/ # Serena AI configuration
|
||||
│ └── memories/ # Project knowledge base
|
||||
├── Makefile # Build automation
|
||||
├── pyproject.toml # Python configuration
|
||||
├── CLAUDE.md # Project instructions
|
||||
└── README.md # Auto-generated catalog
|
||||
```
|
||||
|
||||
## Modular Validator Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
- **BaseValidator**: Abstract interface for all validators
|
||||
- **ValidatorRegistry**: Dynamic discovery and loading
|
||||
- **ConventionMapper**: Automatic validation based on naming patterns
|
||||
|
||||
### Specialized Validators
|
||||
|
||||
1. **TokenValidator**: GitHub, NPM, PyPI, Docker tokens
|
||||
2. **VersionValidator**: SemVer, CalVer, language-specific
|
||||
3. **BooleanValidator**: Case-insensitive boolean values
|
||||
4. **NumericValidator**: Ranges and numeric constraints
|
||||
5. **DockerValidator**: Images, tags, platforms, registries
|
||||
6. **FileValidator**: Paths, extensions, security checks
|
||||
7. **NetworkValidator**: URLs, emails, IPs, ports
|
||||
8. **SecurityValidator**: Injection detection, secrets
|
||||
9. **CodeQLValidator**: Queries, languages, categories
|
||||
|
||||
### Custom Validators
|
||||
|
||||
- `sync-labels/CustomValidator.py` - YAML file validation
|
||||
- `docker-build/CustomValidator.py` - Complex build validation
|
||||
- `codeql-analysis/CustomValidator.py` - Language and query validation
|
||||
- `docker-publish/CustomValidator.py` - Registry and credential validation
|
||||
|
||||
## Action Categories
|
||||
|
||||
### Setup Actions (7)
|
||||
|
||||
- `node-setup`, `set-git-config`, `php-version-detect`
|
||||
- `python-version-detect`, `python-version-detect-v2`
|
||||
- `go-version-detect`, `dotnet-version-detect`
|
||||
|
||||
### Linting Actions (13)
|
||||
|
||||
- `ansible-lint-fix`, `biome-check`, `biome-fix`
|
||||
- `csharp-lint-check`, `eslint-check`, `eslint-fix`
|
||||
- `go-lint`, `pr-lint`, `pre-commit`
|
||||
- `prettier-check`, `prettier-fix`
|
||||
- `python-lint-fix`, `terraform-lint-fix`
|
||||
|
||||
### Build Actions (3)
|
||||
|
||||
- `csharp-build`, `go-build`, `docker-build`
|
||||
|
||||
### Publishing Actions (5)
|
||||
|
||||
- `npm-publish`, `docker-publish`
|
||||
- `docker-publish-gh`, `docker-publish-hub`
|
||||
- `csharp-publish`
|
||||
|
||||
### Testing Actions (3)
|
||||
|
||||
- `php-tests`, `php-laravel-phpunit`, `php-composer`
|
||||
|
||||
### Repository Management (9)
|
||||
|
||||
- `github-release`, `release-monthly`
|
||||
- `sync-labels`, `stale`
|
||||
- `compress-images`, `common-cache`
|
||||
- `common-file-check`, `common-retry`
|
||||
- `codeql-analysis`
|
||||
|
||||
### Utilities (2)
|
||||
|
||||
- `version-file-parser`, `version-validator`
|
||||
|
||||
## Key Architectural Principles
|
||||
|
||||
### Self-Contained Design
|
||||
|
||||
- Each action directory contains everything needed
|
||||
- No dependencies between actions
|
||||
- External usability via `ivuorinen/actions/action-name@main`
|
||||
- Custom validators colocated with actions
|
||||
|
||||
### Modular Validation System
|
||||
|
||||
- Specialized validators for different input types
|
||||
- Convention-based automatic detection (100+ patterns)
|
||||
- Priority system for pattern matching
|
||||
- Error propagation between validators
|
||||
- Full GitHub expression support (`${{ }}`)
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
- **ShellSpec**: Shell scripts and GitHub Actions
|
||||
- **pytest**: Python validation system (100% pass rate)
|
||||
- **Coverage**: All validators have dedicated test files
|
||||
- **Standards**: Zero tolerance for failures
|
||||
|
||||
### Security Model
|
||||
|
||||
- SHA-pinned external actions
|
||||
- Token pattern validation
|
||||
- Injection detection
|
||||
- Path traversal protection
|
||||
- Security validator for sensitive data
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Core Commands
|
||||
|
||||
```bash
|
||||
make all # Full build pipeline
|
||||
make dev # Format and lint
|
||||
make lint # All linters
|
||||
make test # All tests
|
||||
make update-validators # Generate validation rules
|
||||
```
|
||||
|
||||
### Quality Standards
|
||||
|
||||
- **EditorConfig**: Blocking enforcement
|
||||
- **Linting**: Zero issues required
|
||||
- **Testing**: 100% pass rate required
|
||||
- **Production Ready**: Only when ALL checks pass
|
||||
|
||||
### Documentation
|
||||
|
||||
- Auto-generated README files via `action-docs`
|
||||
- Consistent formatting and structure
|
||||
- Cross-referenced action catalog
|
||||
- Comprehensive inline documentation
|
||||
@@ -1,36 +0,0 @@
|
||||
# Quality Standards and Communication Guidelines
|
||||
|
||||
## Critical Quality Standards
|
||||
|
||||
### ZERO TOLERANCE POLICY
|
||||
|
||||
- **ANY failing tests** = Project is NOT production ready
|
||||
- **ANY linting issues** = Project is NOT production ready
|
||||
- **NO EXCEPTIONS** to these rules
|
||||
|
||||
### Production Ready Definition
|
||||
|
||||
A project is only production ready when:
|
||||
|
||||
- ALL tests pass (100% success rate)
|
||||
- ALL linting passes with zero issues
|
||||
- ALL validation checks pass
|
||||
- NO warnings or errors in any tooling
|
||||
|
||||
### Communication Style
|
||||
|
||||
- **Tone down language** - avoid excessive enthusiasm or verbose descriptions
|
||||
- Be direct and factual
|
||||
- Don't claim success until ALL issues are resolved
|
||||
- Don't use terms like "production ready" unless literally everything passes
|
||||
- Focus on facts, not marketing language
|
||||
|
||||
### Work Standards
|
||||
|
||||
- Fix ALL issues before declaring completion
|
||||
- Never compromise on quality standards
|
||||
- Test everything thoroughly
|
||||
- Maintain zero-defect mentality
|
||||
- Quality over speed
|
||||
|
||||
This represents the user's absolute standards for code quality and communication.
|
||||
87
.serena/memories/repository_overview.md
Normal file
87
.serena/memories/repository_overview.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# GitHub Actions Monorepo - Overview
|
||||
|
||||
## Repository Info
|
||||
|
||||
- **Path**: /Users/ivuorinen/Code/ivuorinen/actions
|
||||
- **Branch**: main
|
||||
- **External Usage**: `ivuorinen/actions/<action-name>@main`
|
||||
- **Total Actions**: 43 self-contained actions
|
||||
|
||||
## Structure
|
||||
|
||||
```text
|
||||
/
|
||||
├── <action-dirs>/ # 43 self-contained actions
|
||||
│ ├── action.yml # Action definition
|
||||
│ ├── README.md # Auto-generated
|
||||
│ └── CustomValidator.py # Optional validator
|
||||
├── validate-inputs/ # Centralized validation
|
||||
│ ├── validators/ # 9 specialized modules
|
||||
│ ├── scripts/ # Rule/test generators
|
||||
│ └── tests/ # 769 pytest tests
|
||||
├── _tests/ # ShellSpec framework
|
||||
├── _tools/ # Development utilities
|
||||
├── .github/workflows/ # CI/CD workflows
|
||||
└── Makefile # Build automation
|
||||
```
|
||||
|
||||
## Action Categories (43 total)
|
||||
|
||||
**Setup (7)**: node-setup, set-git-config, php-version-detect, python-version-detect, python-version-detect-v2, go-version-detect, dotnet-version-detect
|
||||
|
||||
**Linting (13)**: ansible-lint-fix, biome-check/fix, csharp-lint-check, eslint-check/fix, go-lint, pr-lint, pre-commit, prettier-check/fix, python-lint-fix, terraform-lint-fix
|
||||
|
||||
**Build (3)**: csharp-build, go-build, docker-build
|
||||
|
||||
**Publishing (5)**: npm-publish, docker-publish, docker-publish-gh, docker-publish-hub, csharp-publish
|
||||
|
||||
**Testing (3)**: php-tests, php-laravel-phpunit, php-composer
|
||||
|
||||
**Repository (9)**: github-release, release-monthly, sync-labels, stale, compress-images, common-cache, common-file-check, common-retry, codeql-analysis
|
||||
|
||||
**Utilities (3)**: version-file-parser, version-validator, validate-inputs
|
||||
|
||||
## Key Principles
|
||||
|
||||
### Self-Contained Design
|
||||
|
||||
- No dependencies between actions
|
||||
- Externally usable via GitHub Actions marketplace
|
||||
- Custom validators colocated with actions
|
||||
|
||||
### Quality Standards
|
||||
|
||||
- **Zero Tolerance**: No failing tests, no linting issues
|
||||
- **Production Ready**: Only when ALL checks pass
|
||||
- **EditorConfig**: 2-space indent, LF, UTF-8, max 200 chars (120 for MD)
|
||||
|
||||
### Security Model
|
||||
|
||||
- SHA-pinned external actions (55 SHA-pinned, 0 unpinned)
|
||||
- Token validation, injection detection
|
||||
- Path traversal protection
|
||||
- `set -euo pipefail` in all shell scripts
|
||||
|
||||
## Development Workflow
|
||||
|
||||
```bash
|
||||
make all # Full pipeline: docs, format, lint, test
|
||||
make dev # Format + lint
|
||||
make lint # All linters (markdownlint, yaml-lint, shellcheck, ruff)
|
||||
make test # All tests (pytest + ShellSpec)
|
||||
```
|
||||
|
||||
## Testing Framework
|
||||
|
||||
- **ShellSpec**: GitHub Actions and shell scripts
|
||||
- **pytest**: Python validators (769 tests, 100% pass rate)
|
||||
- **Test Generator**: Automatic scaffolding for new actions
|
||||
|
||||
## Current Status
|
||||
|
||||
- ✅ All tests passing (769/769)
|
||||
- ✅ Zero linting issues
|
||||
- ✅ Modular validator architecture
|
||||
- ✅ Convention-based validation
|
||||
- ✅ Test generation system
|
||||
- ✅ Full backward compatibility
|
||||
@@ -1,111 +0,0 @@
|
||||
# ShellSpec Test Fixes Tracking
|
||||
|
||||
## Status
|
||||
|
||||
**Branch**: feat/upgrades-and-restructuring
|
||||
**Date**: 2025-09-17
|
||||
**Progress**: Fixed critical test failures
|
||||
|
||||
## Summary
|
||||
|
||||
- Initial failing tests: 27 actions
|
||||
- **Fixed completely**: 3 actions (codeql-analysis, common-cache, common-file-check)
|
||||
- **Partially fixed**: Several others have reduced failures
|
||||
- **Key achievement**: Established patterns for fixing remaining tests
|
||||
|
||||
## ✅ Completed Fixes (3 actions)
|
||||
|
||||
### 1. codeql-analysis
|
||||
|
||||
- Created comprehensive CustomValidator
|
||||
- Fixed all language, token, path, and query validations
|
||||
- Result: **65 examples, 0 failures**
|
||||
|
||||
### 2. common-cache
|
||||
|
||||
- Created CustomValidator for comma-separated paths
|
||||
- Added cache type, paths, keys, env-vars validation
|
||||
- Result: **29 examples, 0 failures** (23 warnings)
|
||||
|
||||
### 3. common-file-check
|
||||
|
||||
- Created CustomValidator for glob patterns
|
||||
- Supports \*, ?, \*\*, {}, [] in file patterns
|
||||
- Result: **17 examples, 0 failures** (12 warnings)
|
||||
|
||||
## 🎯 Key Patterns Established
|
||||
|
||||
### CustomValidator Template
|
||||
|
||||
```python
|
||||
class CustomValidator(BaseValidator):
|
||||
def validate_inputs(self, inputs: dict[str, str]) -> bool:
|
||||
# Handle required inputs first
|
||||
# Use specific validation methods
|
||||
# Check for GitHub expressions: if "${{" in value
|
||||
# Validate security patterns
|
||||
return valid
|
||||
```
|
||||
|
||||
### Common Validation Patterns
|
||||
|
||||
1. **Token Validation**
|
||||
- ghp\_ tokens: 40-44 chars
|
||||
- github*pat* tokens: 82-95 chars
|
||||
- ghs\_ tokens: 40-44 chars
|
||||
|
||||
2. **Path Validation**
|
||||
- Reject absolute paths: `/path`
|
||||
- Reject traversal: `..`
|
||||
- Allow comma-separated: split and validate each
|
||||
|
||||
3. **Error Messages**
|
||||
- "Required input 'X' is missing"
|
||||
- "Absolute path not allowed"
|
||||
- "Path traversal detected"
|
||||
- "Command injection detected"
|
||||
|
||||
4. **Test Output**
|
||||
- Python logger outputs to stderr
|
||||
- Tests checking stdout need updating to stderr
|
||||
- Warnings about unexpected output are non-critical
|
||||
|
||||
## 📋 Remaining Work
|
||||
|
||||
### Quick Fixes (Similar patterns)
|
||||
|
||||
- common-retry: Add backoff-strategy, shell validation
|
||||
- compress-images: File pattern validation
|
||||
- eslint-check, prettier-fix: Token validation
|
||||
|
||||
### Docker Actions (Need CustomValidators)
|
||||
|
||||
- docker-build, docker-publish, docker-publish-gh, docker-publish-hub
|
||||
- Common issues: image-name, registry, platforms validation
|
||||
|
||||
### Version Detection Actions
|
||||
|
||||
- go-version-detect, python-version-detect, php-version-detect
|
||||
- Need version format validation
|
||||
|
||||
### Complex Actions (Need detailed CustomValidators)
|
||||
|
||||
- node-setup: Package manager, caching logic
|
||||
- pre-commit: Hook configuration
|
||||
- terraform-lint-fix: HCL-specific validation
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
To complete all fixes:
|
||||
|
||||
1. Create CustomValidators for remaining actions with failures
|
||||
2. Use established patterns for quick wins
|
||||
3. Test each action individually before full suite
|
||||
4. Update tests expecting stdout to check stderr where needed
|
||||
|
||||
## 📊 Success Criteria
|
||||
|
||||
- All ShellSpec tests pass (0 failures)
|
||||
- Warnings are acceptable (output format issues)
|
||||
- Maintain backward compatibility
|
||||
- Follow established validation patterns
|
||||
@@ -1,125 +0,0 @@
|
||||
# Task Completion Requirements
|
||||
|
||||
## Mandatory Steps After Completing Any Task
|
||||
|
||||
### 1. Linting (BLOCKING REQUIREMENT)
|
||||
|
||||
```bash
|
||||
make lint # Run all linters - must pass 100%
|
||||
```
|
||||
|
||||
**Critical Rules:**
|
||||
|
||||
- EditorConfig violations are BLOCKING errors - fix always
|
||||
- All linting issues are NOT ACCEPTABLE and must be resolved
|
||||
- Never simplify linting configuration to make tests pass
|
||||
- Linting tools decisions are final and must be obeyed
|
||||
- Consider ALL linting errors as blocking errors
|
||||
|
||||
**Specific Linting Steps:**
|
||||
|
||||
```bash
|
||||
make lint-markdown # Fix markdown issues
|
||||
make lint-yaml # Fix YAML issues
|
||||
make lint-shell # Fix shell script issues
|
||||
make lint-python # Fix Python code issues
|
||||
```
|
||||
|
||||
### 2. Testing (VERIFICATION REQUIREMENT)
|
||||
|
||||
```bash
|
||||
make test # Run all tests - must pass 100%
|
||||
```
|
||||
|
||||
**Test Categories:**
|
||||
|
||||
- Python validation tests (pytest)
|
||||
- GitHub Actions tests (ShellSpec)
|
||||
- Integration tests
|
||||
- Coverage reporting
|
||||
|
||||
### 3. Formatting (AUTO-FIX REQUIREMENT)
|
||||
|
||||
```bash
|
||||
make format # Auto-fix all formatting issues
|
||||
```
|
||||
|
||||
**Always use autofixers before running linters:**
|
||||
|
||||
- Markdown formatting and table formatting
|
||||
- YAML/JSON formatting with prettier
|
||||
- Python formatting with ruff
|
||||
- Line ending and whitespace fixes
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
### Before Considering Task Complete
|
||||
|
||||
- [ ] `make lint` passes with zero issues
|
||||
- [ ] `make test` passes with 100% success
|
||||
- [ ] EditorConfig rules followed (2-space indent, LF endings, UTF-8)
|
||||
- [ ] No trailing whitespace or missing final newlines
|
||||
- [ ] Shell scripts pass shellcheck
|
||||
- [ ] Python code passes ruff with comprehensive rules
|
||||
- [ ] YAML files pass yaml-lint and actionlint
|
||||
- [ ] Markdown passes markdownlint-cli2
|
||||
|
||||
### Security and Quality Gates
|
||||
|
||||
- [ ] No secrets or credentials committed
|
||||
- [ ] No hardcoded tokens or API keys
|
||||
- [ ] Proper error handling with `set -euo pipefail`
|
||||
- [ ] External actions are SHA-pinned
|
||||
- [ ] Input validation through centralized system
|
||||
|
||||
## Error Resolution Strategy
|
||||
|
||||
### When Linting Fails
|
||||
|
||||
1. **Read the error message carefully** - don't ignore details
|
||||
2. **Read the linting tool schema** - understand the rules
|
||||
3. **Compare against schema** - schema is the truth
|
||||
4. **Fix the actual issue** - don't disable rules
|
||||
5. **Use autofix first** - `make format` before manual fixes
|
||||
|
||||
### When Tests Fail
|
||||
|
||||
1. **Fix all errors and warnings** - no exceptions
|
||||
2. **Ensure proper test coverage** - comprehensive testing required
|
||||
3. **Verify integration points** - actions must work together
|
||||
4. **Check validation logic** - centralized validation must pass
|
||||
|
||||
### Common Issues and Solutions
|
||||
|
||||
- **EditorConfig**: Use exactly 2 spaces, LF endings, UTF-8
|
||||
- **Python**: Follow Google docstring style, 100 char lines
|
||||
- **Shell**: Use shellcheck-compliant patterns
|
||||
- **YAML**: Proper indentation, no trailing spaces
|
||||
- **Markdown**: Tables formatted, links valid, consistent style
|
||||
|
||||
## Never Do These
|
||||
|
||||
- Never use `git commit` without explicit user request
|
||||
- Never use `--no-verify` flags
|
||||
- Never modify linting configuration to make tests pass
|
||||
- Never assume linting issues are acceptable
|
||||
- Never skip testing after code changes
|
||||
- Never create files unless absolutely necessary
|
||||
|
||||
## File Modification Preferences
|
||||
|
||||
- **Always prefer editing existing files** over creating new ones
|
||||
- **Never proactively create documentation** unless requested
|
||||
- **Read project patterns** before making changes
|
||||
- **Follow existing conventions** in the codebase
|
||||
- **Use centralized validation** for all input handling
|
||||
|
||||
## Final Verification
|
||||
|
||||
After ALL tasks are complete, run the full development cycle:
|
||||
|
||||
```bash
|
||||
make all # Complete workflow: docs, format, lint, test
|
||||
```
|
||||
|
||||
This ensures the project maintains its excellent state and all quality gates pass.
|
||||
76
.serena/memories/validator_system.md
Normal file
76
.serena/memories/validator_system.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Validation System Architecture
|
||||
|
||||
## Status: PRODUCTION READY ✅
|
||||
|
||||
- 769 tests passing (100%)
|
||||
- Zero linting issues
|
||||
- Modular architecture complete
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
- **BaseValidator**: Abstract interface for all validators
|
||||
- **ValidatorRegistry**: Dynamic discovery, loads custom validators from `<action>/CustomValidator.py`
|
||||
- **ConventionMapper**: Auto-detection via 100+ naming patterns (priority-based matching)
|
||||
|
||||
### Specialized Validators (9)
|
||||
|
||||
`token.py`, `version.py` (SemVer/CalVer), `boolean.py`, `numeric.py`, `docker.py`, `file.py`, `network.py`, `security.py`, `codeql.py`
|
||||
|
||||
### Custom Validators (20+)
|
||||
|
||||
Actions with complex validation have `CustomValidator.py` in their directory. Registry auto-discovers them.
|
||||
|
||||
Examples: `docker-build/CustomValidator.py`, `sync-labels/CustomValidator.py`, `codeql-analysis/CustomValidator.py`
|
||||
|
||||
## Convention-Based Detection
|
||||
|
||||
Automatic validator selection from input names:
|
||||
|
||||
- Priority 100: Exact (`dry-run` → boolean)
|
||||
- Priority 95: Language-specific (`-python-version` → python_version)
|
||||
- Priority 90: Suffixes (`-token` → token)
|
||||
- Priority 85: Contains (`email` → email)
|
||||
- Priority 80: Prefixes (`is-` → boolean)
|
||||
|
||||
## Test Generation
|
||||
|
||||
`validate-inputs/scripts/generate-tests.py`:
|
||||
|
||||
- Non-destructive (preserves existing tests)
|
||||
- Intelligent pattern detection for input types
|
||||
- Template-based scaffolding for validators
|
||||
- ShellSpec + pytest generation
|
||||
|
||||
## Usage
|
||||
|
||||
```python
|
||||
from validators.registry import ValidatorRegistry
|
||||
validator = ValidatorRegistry().get_validator("docker-build")
|
||||
result = validator.validate_inputs({"context": ".", "platforms": "linux/amd64"})
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```text
|
||||
validate-inputs/
|
||||
├── validator.py # Main entry
|
||||
├── validators/ # 9 specialized + base + registry + conventions
|
||||
├── scripts/
|
||||
│ ├── update-validators.py # Rule generator
|
||||
│ └── generate-tests.py # Test generator
|
||||
└── tests/ # 769 pytest tests
|
||||
|
||||
<action>/CustomValidator.py # Action-specific validators
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
- Convention-based auto-detection
|
||||
- GitHub expression support (`${{ }}`)
|
||||
- Error propagation between validators
|
||||
- Security validation (injection, secrets)
|
||||
- CalVer, SemVer, flexible versioning
|
||||
- Docker platforms, registries
|
||||
- Token formats (GitHub, NPM, PyPI)
|
||||
Reference in New Issue
Block a user