Initial commit
This commit is contained in:
Zhongwei Li
325
skills/fluxwing-validator/README.md
Normal file
325
skills/fluxwing-validator/README.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# Fluxwing Validator
|
||||
|
||||
Deterministic validation for uxscii components and screens.
|
||||
|
||||
## Two Modes of Operation
|
||||
|
||||
### Interactive Mode (User Invocation)
|
||||
|
||||
When users say "Validate my components", the skill:
|
||||
1. Presents menu (everything/components/screens/custom)
|
||||
2. Runs appropriate validators
|
||||
3. Shows minimal summary with optional details
|
||||
|
||||
**Example:**
|
||||
```
|
||||
✓ 12/14 components valid
|
||||
✗ 2/14 components failed
|
||||
|
||||
Show error details? (yes/no)
|
||||
```
|
||||
|
||||
### Direct Mode (Skill-to-Skill)
|
||||
|
||||
Other skills call validator scripts directly:
|
||||
```bash
|
||||
node {SKILL_ROOT}/../fluxwing-validator/validate-component.js \
|
||||
./fluxwing/components/button.uxm \
|
||||
{SKILL_ROOT}/schemas/uxm-component.schema.json
|
||||
```
|
||||
|
||||
Output: Always verbose (full errors, warnings, stats)
|
||||
Exit codes: 0 = valid, 1 = errors, 2 = invalid args
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This skill contains validation scripts that can be called from Claude Code skills to validate `.uxm` component files against JSON Schema with additional uxscii-specific checks.
|
||||
|
||||
**Key features:**
|
||||
- ✅ **Deterministic** - Locked dependencies via `package-lock.json`
|
||||
- ✅ **Zero setup** - `node_modules` bundled in repository
|
||||
- ✅ **Fast** - ~80ms execution time with ajv
|
||||
- ✅ **Comprehensive** - Schema validation + uxscii-specific rules
|
||||
- ✅ **Structured output** - JSON and human-readable formats
|
||||
|
||||
## Installation
|
||||
|
||||
This skill is bundled with fluxwing-skills plugin.
|
||||
|
||||
**Plugin install:**
|
||||
```bash
|
||||
/plugin install fluxwing-skills
|
||||
```
|
||||
|
||||
**Script install (development):**
|
||||
```bash
|
||||
./scripts/install.sh
|
||||
```
|
||||
|
||||
No npm install required - dependencies bundled with skill.
|
||||
|
||||
## Files
|
||||
|
||||
```
|
||||
skills/fluxwing-validator/
|
||||
├── SKILL.md # Interactive validation workflow
|
||||
├── validate-component.js # Component validator
|
||||
├── validate-screen.js # Screen validator
|
||||
├── validate-batch.js # Batch validator
|
||||
├── test-validator.js # Component test suite
|
||||
├── test-screen-validator.js # Screen test suite
|
||||
├── package.json # Dependencies (ajv 8.12.0)
|
||||
├── package-lock.json # Locked versions
|
||||
├── node_modules/ # Bundled dependencies (~7.4 MB)
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### From Command Line
|
||||
|
||||
```bash
|
||||
# From project root
|
||||
node skills/fluxwing-validator/validate-component.js \
|
||||
./fluxwing/components/component.uxm \
|
||||
skills/fluxwing-component-creator/schemas/uxm-component.schema.json
|
||||
|
||||
# JSON output (for programmatic use)
|
||||
node skills/fluxwing-validator/validate-component.js \
|
||||
./fluxwing/components/component.uxm \
|
||||
skills/fluxwing-component-creator/schemas/uxm-component.schema.json \
|
||||
--json
|
||||
```
|
||||
|
||||
### From Other Skills (using SKILL_ROOT)
|
||||
|
||||
```bash
|
||||
# In SKILL.md - Direct mode validation
|
||||
node {SKILL_ROOT}/../fluxwing-validator/validate-component.js \
|
||||
./fluxwing/components/button.uxm \
|
||||
{SKILL_ROOT}/schemas/uxm-component.schema.json
|
||||
```
|
||||
|
||||
### Exit Codes
|
||||
|
||||
- `0` - Component is valid
|
||||
- `1` - Validation errors found
|
||||
- `2` - Missing dependencies or invalid arguments
|
||||
|
||||
## Validation Checks
|
||||
|
||||
### 1. JSON Schema Validation
|
||||
|
||||
Validates against `uxm-component.schema.json` using ajv (Draft 7):
|
||||
- Required fields (id, type, version, metadata, props, ascii)
|
||||
- Field types and formats
|
||||
- Enum constraints (type, category, fidelity)
|
||||
- Pattern matching (id format, version format)
|
||||
- Array and object structures
|
||||
|
||||
### 2. ASCII Template File
|
||||
|
||||
- Checks that corresponding `.md` file exists
|
||||
- Validates path: `component.uxm` → `component.md`
|
||||
|
||||
### 3. Template Variables
|
||||
|
||||
- Extracts `{{variables}}` from `.md` template
|
||||
- Compares against `ascii.variables` in `.uxm`
|
||||
- Warns if variables in `.md` are not defined in `.uxm`
|
||||
- Supports both formats:
|
||||
- Array of strings: `["text", "value"]`
|
||||
- Array of objects: `[{"name": "text", "type": "string"}]`
|
||||
|
||||
### 4. Accessibility
|
||||
|
||||
For interactive components (with `behavior.interactions`):
|
||||
- Warns if missing `behavior.accessibility.role`
|
||||
- Warns if `focusable` is not set
|
||||
|
||||
### 5. ASCII Dimensions
|
||||
|
||||
- Warns if `ascii.width` > 120 (terminal width limit)
|
||||
- Warns if `ascii.height` > 50 (single viewport limit)
|
||||
|
||||
### 6. State Properties
|
||||
|
||||
- Warns if states exist but have no properties defined
|
||||
|
||||
## Output Format
|
||||
|
||||
### Human-Readable
|
||||
|
||||
```
|
||||
✓ Valid: primary-button
|
||||
Type: button
|
||||
Version: 1.0.0
|
||||
States: 4
|
||||
Props: 5
|
||||
|
||||
Warnings: 1
|
||||
1. Interactive component should have ARIA role
|
||||
Location: behavior → accessibility → role
|
||||
```
|
||||
|
||||
### JSON
|
||||
|
||||
```json
|
||||
{
|
||||
"valid": true,
|
||||
"errors": [],
|
||||
"warnings": [
|
||||
{
|
||||
"path": ["behavior", "accessibility", "role"],
|
||||
"message": "Interactive component should have ARIA role",
|
||||
"type": "accessibility"
|
||||
}
|
||||
],
|
||||
"stats": {
|
||||
"id": "primary-button",
|
||||
"type": "button",
|
||||
"version": "1.0.0",
|
||||
"states": 4,
|
||||
"props": 5,
|
||||
"interactive": true,
|
||||
"hasAccessibility": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
Only 6 packages, 2.7 MB total:
|
||||
|
||||
- `ajv@8.12.0` - JSON Schema validator (industry standard)
|
||||
- `ajv-formats@2.1.1` - Format validation (date-time, etc.)
|
||||
- Supporting packages (fast-deep-equal, fast-uri, json-schema-traverse, require-from-string)
|
||||
|
||||
**All dependencies are bundled in `node_modules/` and checked into git.**
|
||||
|
||||
## Node.js Version
|
||||
|
||||
- **Minimum:** Node.js 14.0.0
|
||||
- **Recommended:** Node.js 18+ or 20+ (LTS)
|
||||
- **Tested:** Node.js 18, 20, 22
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Run test suite against bundled templates
|
||||
npm test
|
||||
|
||||
# Or directly
|
||||
node test-validator.js
|
||||
```
|
||||
|
||||
Tests validate components from:
|
||||
- `skills/fluxwing-component-creator/templates/*.uxm`
|
||||
|
||||
## Development
|
||||
|
||||
### Updating Validation Logic
|
||||
|
||||
1. Edit `validate-component.js`
|
||||
2. Test changes: `npm test`
|
||||
3. Commit (no build step needed)
|
||||
|
||||
### Updating Dependencies
|
||||
|
||||
```bash
|
||||
npm update
|
||||
npm audit fix
|
||||
npm test
|
||||
git add package-lock.json node_modules/
|
||||
git commit -m "Update dependencies"
|
||||
```
|
||||
|
||||
### Adding New Validators
|
||||
|
||||
Create new scripts following the same pattern:
|
||||
- `validate-screen.js` - For screen validation
|
||||
- `validate-variable.js` - For variable substitution
|
||||
|
||||
## Why Node.js?
|
||||
|
||||
Compared to Python or native binaries:
|
||||
|
||||
**Advantages:**
|
||||
- ✅ No build step (unlike Go/Rust/Deno compiled)
|
||||
- ✅ Readable source code (easier debugging)
|
||||
- ✅ Small diffs (text, not binaries)
|
||||
- ✅ Likely installed (most developers have Node.js)
|
||||
- ✅ Mature ecosystem (ajv is industry standard)
|
||||
- ✅ Fast enough (~80ms including startup)
|
||||
|
||||
**Tradeoffs:**
|
||||
- ⚠️ Requires Node.js runtime (not zero-dependency)
|
||||
- ⚠️ Slower than native (~80ms vs ~5ms for Go)
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Component Creator Skill
|
||||
|
||||
```bash
|
||||
# After creating component (from SKILL.md)
|
||||
node {SKILL_ROOT}/../fluxwing-validator/validate-component.js \
|
||||
./fluxwing/components/${COMPONENT_ID}.uxm \
|
||||
{SKILL_ROOT}/schemas/uxm-component.schema.json
|
||||
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✓ Component validated successfully"
|
||||
else
|
||||
echo "✗ Validation failed - see errors above"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Pre-commit Hook
|
||||
|
||||
```bash
|
||||
# .claude/hooks/pre-commit.sh
|
||||
for uxm_file in fluxwing/components/*.uxm; do
|
||||
node skills/fluxwing-validator/validate-component.js \
|
||||
"$uxm_file" \
|
||||
skills/fluxwing-component-creator/schemas/uxm-component.schema.json \
|
||||
|| exit 1
|
||||
done
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "ajv libraries not found"
|
||||
|
||||
The validator couldn't find the ajv dependency. This should never happen since `node_modules/` is bundled, but if it does:
|
||||
|
||||
```bash
|
||||
cd skills/fluxwing-validator
|
||||
npm install
|
||||
```
|
||||
|
||||
### "Component file not found"
|
||||
|
||||
Check that the path to the `.uxm` file is correct. Paths are relative to the current working directory.
|
||||
|
||||
### "Invalid JSON"
|
||||
|
||||
The `.uxm` file has syntax errors. Use a JSON validator to find the issue:
|
||||
|
||||
```bash
|
||||
cat component.uxm | jq .
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- [x] Screen validation (`validate-screen.js`)
|
||||
- [x] Batch validation (`validate-batch.js`)
|
||||
- [ ] Variable substitution validation
|
||||
- [ ] Watch mode for development
|
||||
- [ ] Integration with CI/CD pipelines
|
||||
- [ ] VSCode extension integration
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user