feat: add stateful CPU percentage counter

Load is a delta, so one reading cannot yield a percentage. The first
call returns nil rather than a fabricated number: 100% on startup reads
as a real spike.

A non-advancing counter also returns nil instead of dividing by zero,
and the result is clamped because a suspend/resume can produce a
nonsense delta.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 18 insertions, 0 deletions

diff --git a/test/test_data.lua b/test/test_data.lua
index 08c20f9..44e9ab3 100644
--- a/test/test_data.lua
+++ b/test/test_data.lua
@@ -36,4 +36,22 @@ assert(data.millidegrees(nil) == nil, 'nil input must give nil')
 assert(data.millidegrees('') == nil, 'empty input must give nil')
 assert(data.millidegrees('garbage') == nil, 'unparseable input must give nil')
 
+-- cpu_percent is a delta between two samples, so it holds state.
+-- The first call has no previous sample and must report nil, not a number:
+-- any number it invented would be wrong, and 100% on startup looks like a
+-- real spike.
+local c = data.new_cpu_counter()
+assert(c:sample(1000, 900) == nil, 'first sample must give nil')
+
+-- Second sample: 100 more total jiffies, 50 of them idle, so 50% busy.
+-- Held in a local first: calling sample() again inside the assert message would
+-- advance the counter a third time.
+local busy = c:sample(1100, 950)
+assert(busy == 50.0, 'second sample, got ' .. tostring(busy))
+
+-- A counter that did not advance means no elapsed time, not 0% load.
+local c2 = data.new_cpu_counter()
+c2:sample(1000, 900)
+assert(c2:sample(1000, 900) == nil, 'zero delta must give nil, not a division by zero')
+
 print('test_data: all assertions passed')