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

1.5 KiB

Development

This document covers contributor workflows for Win Diagnostics. Runtime usage is documented in the main README.

Test environment

Tests require uv. test.sh creates .venv and synchronizes the pinned packages from tests/requirements.txt, and invokes Python only from that environment.

./tests/test.sh

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:

  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 ./tests/test.sh 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/Typst based.