# Diagnostics reports `diagnostics.typ` generates a synthetic Windows health assessment from the structured JSON report produced by `windiagnostics/WindowsMaintenanceReport.ps1`. ## Quick start Collect a Full report on Windows, copy the resulting `.json` file into `diagnostics/`, then run from this repository: ```bash ./render-diagnostics.sh diagnostics/windows_system_report_PC.json "Your Name" ``` The theme is optional and defaults to `default`. Choose a theme with the optional third argument: ```bash ./render-diagnostics.sh diagnostics/windows_system_report_PC.json "Your Name" eridani ``` Render every `.json` dump under `diagnostics/` recursively: ```bash ./render-diagnostics.sh --all "Your Name" ``` Select a non-default theme for the complete batch: ```bash ./render-diagnostics.sh --all "Your Name" cic ``` Nested source directories are reproduced under `build/diagnostics/`, preventing reports with identical filenames from overwriting one another. The command creates: ```text build/diagnostics/windows_system_report_PC.pdf ``` The author is mandatory. The diagnostic date comes from the report's `generated_at` field and is also mandatory. Missing values stop compilation with an explicit message. ## Pipeline 1. `diagnostics-normalize.typ` reads WinDiagnostics schema version 1 JSON, deduplicates event records, classifies signals, and builds normalized data entirely inside Typst. 2. `diagnostics.typ` validates the inputs and selected YAML theme. 3. `diagnostics-model.typ` renders the final PDF and uses PrimaViz for the summary visualization. No Python conversion or external normalization step is required for native captures. Typst reads the `.json` dump directly. It downloads `@preview/primaviz:0.10.0` on the first build and caches it locally. The normalizer also correlates CatRoot2 checksum errors with CryptSvc crashes in ESENT.dll and Windows Update failures within two minutes of a checksum event. When all three signals are present, the generated PDF includes a priority finding and a shared investigation plan. Individual events remain visible; the correlation adds no extra health-score penalty. This identifies a related failure sequence, not a proven hardware root cause. Disabled display adapters receive Code 22 guidance, and non-elevated captures receive a coverage warning. Run the parser and correlation regression checks with: ```bash typst compile --root . tools/check-diagnostics.typ /tmp/check-diagnostics.pdf ``` ## Report structure The document is divided into three purposeful parts: 1. **Executive overview** — the short first-page health assessment, capacity metrics, heuristic health graph, priority findings, and signal chart. 2. **Findings requiring attention** — a resolution plan for every actionable exception, followed by its correlated, deduplicated event evidence. 3. **Technical evidence** — system context, storage capacity, inventory counts, selected source output, and collector-coverage audit. The executive overview is deliberately short: - overall assessment; - critical and warning counts; - a health score and aggregate analysis confidence; - maximum installed memory and aggregate analysis confidence; - the four highest-priority findings; - a compact free-space chart for every captured volume. The remaining two parts contain: - system and storage profile; - inventory counts instead of full healthy inventories; - all actionable findings; - deduplicated event-log evidence; - selected source evidence for hardware, storage, security, networking, power, DISM, and SFC; - a collector-coverage table describing how every source section was used. ## Noise and privacy policy The report favors exceptions over exhaustive reproduction: - repeated identical event records are collapsed and counted; - related event variants share one top-level finding; - installed applications, Store packages, services, drivers, tasks, startup entries, and listeners are counted rather than listed in full; - SFC progress lines are removed while its final result is retained; - raw IP configuration, user paths, and other noise-heavy or sensitive values are reviewed but not reproduced; - healthy status remains visible in relevant summaries but does not create an individual finding. Routine evidence is conditional: - vanilla enabled firewall profiles are omitted; - Defender details are omitted when all collected protection flags are true; - component-store output is omitted when it contains no repairable, corruption, or error signal; - battery output is omitted when WMI reports `OK` and at least 20% charge; - DNS servers, power-plan details, and stopped automatic-service snapshots are omitted from evidence but remain accounted for in collector coverage; - SFC integrity failures are retained and highlighted as critical. ## Upgradeable event heuristics Event interpretation lives in `diagnostics-rules.yaml`, separate from the Typst parser and layout. Each rule matches an exact provider and event ID and defines its severity, rationale, and a heuristic confidence estimate: ```yaml event_rules: - provider: "Service Control Manager" id: "7000" severity: "warning" confidence: 90 rationale: "A configured service or driver failed to start." ``` If no rule matches, the event is retained as `unanalysed` and visibly labelled `FAIL TO ANALYSE`. Add or revise a rule, then rerun the same render command; no Typst code change is required. Rules can also provide `resolution_steps`, `reference_url`, and `reference_label`. The **Resolution plan** prints numbered steps and an optional clickable authoritative reference beside the corresponding problem. The older `remediation` string remains a supported fallback. Built-in DISM, SFC, firewall, and device findings provide the same guidance even though they do not originate from an event rule. Confidence percentages are review-priority estimates attached to each classification, not measured failure probabilities. Unknown event rules receive 20% confidence and remain labelled `FAIL TO ANALYSE`. The overview confidence is the arithmetic mean of displayed finding confidence values. The health graph is deliberately simple and reproducible: it begins at 100, subtracts 8 points per critical finding, 2 per warning, and 1 per unanalysed signal, then clamps the result to 0–100. Change those weights in `diagnostics-normalize.typ` if operational experience calls for different priorities. ## Closing findings safely “Clear” means proving that the underlying condition is resolved and producing a new diagnostic capture. It does not mean deleting evidence from Event Viewer. Use this workflow for each item in the PDF's **Resolution plan**: 1. Save the original PDF and JSON capture if the issue may need escalation or an audit trail. 2. Follow the finding's numbered **Resolution path**. Use its linked vendor or Microsoft guidance when one is provided. 3. Perform the stated verification before considering the issue closed. A command completing without an error is not sufficient if the affected service, application, update, backup, or device still fails. 4. Reboot when the repair changes system files, drivers, services, firmware, or pending installer state. 5. Reproduce the original workload where practical, then run WinDiagnostics again and compile the new dump. 6. Compare the new report with the saved report. Close a finding only when its current-state check is healthy or the triggering behavior no longer recurs. Typical closure checks: | Finding | What proves it is cleared | | --- | --- | | DISM / component store | `/RestoreHealth` succeeds and a new health check reports no component-store corruption. | | SFC integrity | `sfc /scannow` completes and reports no remaining integrity violations. | | Firewall | Domain, Private, and Public profiles are enabled, unless a documented organization policy intentionally differs. | | Service failure | The owning software or driver is repaired, the service starts or stops normally, and the event does not recur after a relevant reboot or test. | | Application crash or hang | The repaired or updated application completes the previously failing workflow without a matching new event. | | Windows Update / MSI | The named update or product installation completes successfully and is shown as installed. | | VSS / Volsnap | `vssadmin list writers` shows stable writers and a new backup or shadow copy succeeds. | | Device problem | Device Manager and the next diagnostic capture report the device as healthy. | | Unexpected shutdown | Record the known cause if intentional; otherwise investigate correlated power, bug-check, thermal, driver, and hardware evidence before closure. | | Unknown event | Review the raw provider, ID, and message; add a defensible rule and rerun the report. | Historical events can remain visible after a successful repair because they describe what happened during the collector's look-back window. Leave them intact. A resolved event finding will age naturally and eventually leave future captures; eligible findings may also receive the limited score fading described below. If a clean post-repair capture is needed for handoff, wait until the collector window has advanced rather than clearing the Windows logs. ### Age fading Selected event rules may set `fading: true`. Their health-score penalty remains at full value for seven days, then decreases linearly until it reaches 50% at 90 days. It never falls below 50%; the finding, severity, evidence, and resolution path remain in the report. A faded finding shows its age-adjusted weight beside the finding text. Age is measured from the event timestamp to the diagnostic report date in the report's `generated_at` field. It never uses the current date or the date on which the PDF happens to be compiled. If either date cannot be parsed, full weight is retained. Fading is enabled only for events expected to re-log on recurrence or whose old instance becomes less useful with time: service start/stop failures, application crashes and hangs, Windows Update failures, and installer failures. It is deliberately disabled for storage-controller errors, TPM attestation, firewall, SFC/DISM, VSS/Volsnap, NDIS power transitions, unexpected shutdowns, devices, and unknown events. Those signals may be persistent, intermittent, or unsafe to treat as resolved merely because no newer event was captured. The defaults can be overridden per safe rule with `fade_after_days` and `fade_to_half_days` in `diagnostics-rules.yaml`. A DISM result of `repairable` is classified as a warning, not a critical finding. Microsoft distinguishes it from a non-repairable image and provides `/RestoreHealth` as its normal repair path. System-file integrity violations, TPM pre-attestation failures, and incomplete firewall protection retain their higher operational priority. Do not clear Windows event logs merely to make a diagnostic report look clean. An event is historical evidence, not a live alarm. Resolve its cause, perform the stated verification, and rerun WinDiagnostics; old entries naturally leave the report once they fall outside its configured event-history window. Preserve logs needed for incident investigation or audit. The current rules use conservative interpretations of Windows collector data. For example, Microsoft documents Event 7000 as a service-start failure, `Get-MpComputerStatus` boolean fields as protection-state indicators, and `Win32_Battery.EstimatedChargeRemaining` as remaining charge percentage. Links to those references are kept here for future rule maintenance: - [Service Control Manager Event 7000](https://learn.microsoft.com/en-us/troubleshoot/windows-client/setup-upgrade-and-drivers/system-log-event-id-7000-7026) - [Microsoft Defender status fields](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/defender/msft-mpcomputerstatus) - [Win32_Battery fields](https://learn.microsoft.com/en-us/windows/win32/cimwin32prov/win32-battery) - [DISM and SFC repair sequence](https://support.microsoft.com/en-us/windows/experience/backup-recovery/using-system-file-checker-in-windows) - [Enable Windows Firewall profiles](https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/configure-with-command-line) The final coverage table prevents silent omission: every section emitted by the collector is listed with its treatment. False positives remain possible because classification is heuristic; the PDF says so explicitly. ## Direct Typst usage The JSON capture is passed directly to Typst: ```bash typst compile \ --input diagnostics=diagnostics/windows_system_report_PC.json \ --input author="Your Name" \ --input theme=cic \ diagnostics.typ \ build/diagnostics/report.pdf ``` Available themes are `default`, `cic`, and `eridani` and are defined in `themes.yaml`. ## Input expectations The parser is designed for Compact, Mid, and Full WinDiagnostics JSON captures, but Full provides the evidence needed for meaningful fault synthesis. Unknown future sections remain listed in coverage as retained in the source without specific analysis. ## JSON migration and converted captures The schema follows [WindowsMaintenanceReport.ps1](https://proxy.dandaedre.com/gitea/Beffroi/WinDiagnostics/raw/branch/main/WindowsMaintenanceReport.ps1). The renderer validates `report_type`, `schema_version`, and `generated_at`. Full/Mid captures use section envelopes (`status`, `count`, `data`, `error`); Compact captures use `summary`. Collector warnings and skipped/error sections remain visible. Coverage counts are records, not transcript lines. Native PowerShell dates may use `/Date(milliseconds)/`; ISO timestamps and their offsets are also supported for event correlation. Firewall `Enabled` accepts JSON `true` and the collector's numeric enum value `1`. DISM/SFC output remains text inside JSON; progress lines are removed before displaying evidence. The existing `hardware-*` captures were converted with a lossy converter. It changed CIM keys to snake_case, split event-message fields, and mistook table separators for section headings. Several inventories contain only headers, storage volumes are missing, and an empty section name contains displaced data. These source files are preserved. The renderer accepts recoverable field aliases, retains extra event-message fields, and reads command conclusions from `legacy_raw`. Header-only inventory counts display **Unavailable**; unparsed device/firewall tables do not produce false device or disabled-firewall findings. Every converted report receives an explicit incomplete-evidence finding. Legacy local event timestamps are left unchanged without age fading or temporal correlation because their date order/timezone is not established reliably. Recollect native Full JSON to replace the missing evidence; the renderer cannot reconstruct lost table rows reliably from these JSON files. Native event timestamps display as `YYYY-MM-DD HH:MM:SS UTC`, with raw timestamps preserved internally for correlation and fading. WER-SystemErrorReporting 1001 is a critical kernel-crash finding; code 0x133 is identified as [DPC_WATCHDOG_VIOLATION](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/bug-check-0x133-dpc-watchdog-violation). The saved dump must be analyzed to identify the responsible component. `volmgr` 162 records successful dump generation and is informational, so it adds no health-score penalty and is omitted from actionable event evidence.