Development setup¶
TestSeal is a monorepo with a Python analyzer, TypeScript GitHub Action, and Next.js landing site.
Repository layout¶
packages/testseal/ Python core and tests
packages/action/ TypeScript Action adapter and generated bundle
site/ Next.js and Tailwind landing site
docs/ MkDocs documentation sources
examples/ Configuration and diff examples
scripts/ Release and smoke-test utilities
Clone¶
Python environment¶
Python 3.11 or newer is required. Python 3.12 is the primary development version.
Run Python verification:
python -m ruff check packages/testseal/src packages/testseal/tests scripts
python -m ruff format --check packages/testseal/src packages/testseal/tests scripts
python -m pytest
python scripts/verify_example.py
Run branch coverage locally:
GitHub Action¶
Node.js 24 or newer is required:
npm run verify checks formatting, lint, types, tests, coverage, and the
production bundle. Commit dist/index.js and dist/licenses.txt whenever
runtime source or dependencies change. CI rejects a stale bundle.
Do not edit files in dist directly.
Landing site¶
Use the environment variables documented in site/.env.example for local
metadata testing.
Documentation¶
Install and serve the docs:
The local site is available at http://127.0.0.1:8000. Run the strict build
before committing:
The output goes to .docs-site/, not the Next.js site/ directory.
Build the Python distribution¶
Install and smoke-test the wheel in a clean environment before a release.
Also extract the source distribution and run python -m pytest from its root;
it includes the Python tests and their release-check helper. The package CI job
runs this check outside the checkout so missing distribution files cannot be
supplied accidentally by the repository.
Pre-commit¶
The TestSeal hook itself scans staged changes, so an all-files invocation does not create a synthetic diff for detection tests.
Change discipline¶
- Add focused regression tests for behavior changes.
- Keep rule matching deterministic and side-effect free.
- Preserve the trust boundary: do not import or execute target code.
- Update documentation and examples with public contract changes.
- Keep JSON schema compatibility or version the schema deliberately.
- Regenerate the Action bundle when its runtime changes.
Read CONTRIBUTING.md
for commit, pull request, and review expectations.