diff --git a/README.md b/README.md index 2881181..80e2d81 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,8 @@ as `unanalysed`. It does not render reports or PDFs. ## Requirements -Runtime analysis requires Bash, jq, and standard Unix utilities. Python and uv -are used only for tests. The component has no dependency on Reportist, Beffroi +Runtime analysis requires Bash, jq, and standard Unix utilities. The component +has no dependency on Reportist, Beffroi Reports, or the integration workspace. ## Analyse a capture @@ -59,17 +59,13 @@ is available at [schemas/diagnostic.schema.json](schemas/diagnostic.schema.json) | `1` | Input, contract, evidence, or I/O failure | | `2` | Invalid command-line usage | -## Testing - -Run the contract, rule, fixture, and standalone tests in a uv-managed environment: - -```bash -make test -``` - The fixtures are synthetic and sanitized. See [docs/standalone.md](docs/standalone.md) for privacy guidance and troubleshooting. +## Contributing + +See the [contributor guide](docs/development.md). + ## License The software is licensed under the MIT License. Diagnostic data produced or diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..1453cfd --- /dev/null +++ b/docs/development.md @@ -0,0 +1,39 @@ +# 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.