This repository has been archived on 2026-09-16. You can view files and clone it, but cannot push or open issues or pull requests.
win-diagnostics-analysis/docs/development.md

40 lines
1.4 KiB
Markdown

# Development
This document covers contributor workflows for Win Diagnostics. Runtime usage
is documented in the main [README](../README.md).
## Test environment
Tests require uv. The Makefile creates `.venv`, synchronizes the pinned packages
from `requirements.txt`, and invokes Python only from that environment.
```bash
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/jq 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:
1. Add or update a sanitized fixture that exercises the behavior.
2. Verify finding identity, severity, confidence, and evidence references.
3. Confirm incomplete collection cannot imply a healthy result.
4. Run `make test` and `git 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/jq based.