1.4 KiB
Development
This document covers contributor workflows for Win Diagnostics. Runtime usage is documented in the main README.
Test environment
Tests require uv. The Makefile creates .venv, synchronizes the pinned packages
from requirements.txt, and invokes Python only from that environment.
make test
The suite covers diagnostic contract validation, evidence hashes and JSON Pointers, supported capture schemas, collection limitations, deterministic analysis, event grouping, the complete rule catalog, watchlist gates, standalone operation, and the production shell/Typst runtime.
Rule maintenance
Event classifications live in rules/event-rules.json; advisory software and
driver checks live in rules/watchlist.json. Keep rule descriptions factual and
traceable. A match must not claim causality, exploitation, or hardware failure
without corresponding evidence.
When changing a rule:
- Add or update a sanitized fixture that exercises the behavior.
- Verify finding identity, severity, confidence, and evidence references.
- Confirm incomplete collection cannot imply a healthy result.
- Run
make testandgit diff --check.
Contract changes
schemas/diagnostic.schema.json is a public interface. Preserve compatibility
for existing consumers or introduce a new schema version with documented
mapping. Keep test-only Python support code under tests/; production analysis
and validation remain shell/Typst based.