Companion to StructKit. Pre-commit hooks that validate .struct.yaml before it lands. Star the core repo.
- structkit-validate: Validates YAML syntax and StructKit schema compliance
- structkit-lint: Performs quality and safety checks on structure definitions
Both hooks run automatically on staged files matching the patterns:
.struct.yaml*.struct.yamlstructures/**/*.yamlstructures/**/*.yml
Add to your .pre-commit-config.yaml:
repos:
- repo: https://github.com/httpdss/structkit-pre-commit
rev: v1.0.0 # Use the latest release
hooks:
- id: structkit-validate
- id: structkit-lintNote: Always use a specific release tag (e.g., v1.0.0) for the rev field, not main or a branch name. This ensures reproducible pre-commit environments.
You can also use a floating major version tag (e.g., rev: v1) to automatically receive minor and patch updates, though full version tags are recommended for maximum reproducibility.
Then install the hooks:
pre-commit installValidates that StructKit YAML files are syntactically correct and conform to the StructKit schema.
What it checks:
- YAML syntax validity
- Top-level structure (must be a mapping)
- Required keys and value types
- File and folder configurations
- Variable declarations
- Hook definitions
Example output on error:
StructKit Validate...........................................................Failed
- hook id: structkit-validate
- exit code: 1
❗ Invalid YAML in .struct.yaml: mapping values are not allowed here
Performs advanced quality and safety checks on StructKit structure definitions.
What it checks:
- Undefined template variables
- Unused declared variables
- Template syntax errors
- Duplicate entries (files, folders, variables)
- Unsafe hook commands (e.g.,
rm -rf /, piping to shell) - Unpinned remote URLs
- Missing descriptions
- Naming conventions
Example output:
StructKit Lint...............................................................Passed
Linted 1 file(s): 0 error(s), 2 warning(s)
WARNING: .struct.yaml: [missing-description] Missing top-level description.
WARNING: .struct.yaml (files.README.md): [unpinned-remote-url] Remote URL is not pinned to a stable ref
You can customize which files the hooks run on:
repos:
- repo: https://github.com/httpdss/structkit-pre-commit
rev: v1.0.0
hooks:
- id: structkit-validate
files: ^structures/.*\.ya?ml$
- id: structkit-lint
files: \.struct\.yaml$If you want to treat lint warnings as non-fatal:
repos:
- repo: https://github.com/httpdss/structkit-pre-commit
rev: v1.0.0
hooks:
- id: structkit-validate
- id: structkit-lint
# Currently lint exits with code 1 on errors onlyYou can run the hooks manually on specific files:
# Validate all structure files
pre-commit run structkit-validate --all-files
# Lint only staged files
pre-commit run structkit-lint
# Run on a specific file
pre-commit run structkit-validate --files .struct.yamlThese hooks work seamlessly in CI environments. Add to your CI workflow:
# GitHub Actions example
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install pre-commit
run: pip install pre-commit
- name: Run pre-commit hooks
run: pre-commit run --all-files- Python 3.8+
- pre-commit
- structkit (installed automatically)
To test the hooks without pre-commit:
# Install in development mode
pip install -e .
# Run validate hook
structkit-validate-hook .struct.yaml
# Run lint hook
structkit-lint-hook .struct.yaml structures/*.yamlStructKit is a YAML-based project scaffolding tool that helps you define and generate project structures from templates. It supports:
- Remote content from GitHub, S3, GCS, HTTP
- Template variables with Jinja2
- Pre/post generation hooks
- MCP integration for AI-assisted development
Contributions welcome! Please open an issue or pull request on GitHub.
Apache-2.0 - see LICENSE for details.