# Template Validation Scripts

This repository includes automated validation scripts to ensure template consistency and catch common issues.

## Scripts

### `scan_placeholders.py`
Validates HTML template files for placeholder and conditional block issues.

**Features:**
- ✅ Validates `###IF_xxx###` and `###END_IF_xxx###` block matching
- ✅ Reports line numbers for easy debugging
- ✅ Auto-validates 200307 pricing tags (valid for non-English users)
- ✅ Identifies suspicious placeholders only in non-English files
- ✅ Error-only reporting by default

**Usage:**
```bash
# Basic validation (errors only)
uv run scan_placeholders.py

# Detailed analysis
uv run scan_placeholders.py --verbose

# Check specific file
uv run scan_placeholders.py --file cc/en/download_full.html
```

### `analyze_css.py`
Analyzes CSS class and ID usage across HTML templates.

**Features:**
- ✅ Finds missing CSS definitions (used but not defined)
- ✅ Identifies unused CSS rules (defined but not used)
- ✅ Filters out Bootstrap framework classes
- ✅ Excludes template placeholders and hex colors

**Usage:**
```bash
# Basic analysis (errors only)
uv run analyze_css.py

# Detailed analysis
uv run analyze_css.py --verbose

# Analyze specific file
uv run analyze_css.py --file cc/en/index.html
```

## GitHub Workflow

The repository includes a GitHub Actions workflow (`.github/workflows/template-validation.yml`) that automatically:

1. **Runs on every push/PR** that modifies HTML templates
2. **Validates all templates** for IF/END_IF block consistency
3. **Analyzes CSS usage** and reports missing definitions
4. **Fails the build** if critical template errors are found
5. **Uploads detailed reports** as artifacts for review

### Workflow Triggers
- Push to `master`/`main` branch
- Pull requests to `master`/`main` branch
- Changes to HTML files in `cc/` or `ww/` directories
- Changes to validation scripts

### Workflow Results
- ✅ **PASSED**: All templates are valid
- ❌ **FAILED**: Critical IF/END_IF block errors found
- ⚠️ **WARNINGS**: CSS issues found (non-blocking)

## Common Issues and Fixes

### IF/END_IF Block Mismatches
**Problem:** Mismatched or unclosed conditional blocks
```html
###IF_SOMETHING###
  Content here
###END_IF_SOMETHING_ELSE###  <!-- Wrong! -->
```

**Solution:** Ensure every IF has a matching END_IF
```html
###IF_SOMETHING###
  Content here
###END_IF_SOMETHING###  <!-- Correct! -->
```

### Missing DIVIDE Placeholders
**Problem:** Missing `###DIVIDE###` in changeemail.html files
```html
###IF_CHANGED###
<section>...</section>
###END_IF_CHANGED###  <!-- Missing DIVIDE -->
```

**Solution:** Add DIVIDE placeholder
```html
###IF_CHANGED###
<section>...</section>
###DIVIDE###

###END_IF_CHANGED###
```

### Malformed Placeholders
**Problem:** Wrong number of hash symbols
```html
##END_IF_ERROR##  <!-- Wrong! -->
```

**Solution:** Use exactly three hash symbols
```html
###END_IF_ERROR###  <!-- Correct! -->
```

## Development

### Requirements
- Python 3.11+
- uv package manager

### Running Locally
```bash
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run validation
uv run scan_placeholders.py
uv run analyze_css.py
```

### Adding New Validations
1. Modify the appropriate script (`scan_placeholders.py` or `analyze_css.py`)
2. Test locally with various template files
3. Update this documentation if needed
4. The GitHub workflow will automatically use the updated scripts

## File Structure
```
├── .github/workflows/
│   └── template-validation.yml    # GitHub Actions workflow
├── cc/                           # Crossword Compiler templates
│   ├── en/                       # English templates
│   ├── es/                       # Spanish templates
│   └── ...                       # Other languages
├── ww/                           # WordWeb templates
├── scan_placeholders.py          # Template validation script
├── analyze_css.py               # CSS analysis script
└── TEMPLATE_VALIDATION.md       # This documentation
```

## Troubleshooting

### Script Fails to Run
- Ensure `uv` is installed: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Check Python version: `python --version` (requires 3.11+)

### False Positives
- 200307 pricing tags in non-English files are automatically validated as correct
- Bootstrap classes are filtered out from CSS analysis
- Template placeholders are excluded from CSS ID analysis

### Getting Help
- Check the uploaded artifacts in failed GitHub Actions runs
- Run scripts locally with `--verbose` flag for detailed output
- Use `--file` option to debug specific template files