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.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/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.