code wiki / _hdl_build / nx_clarity.nx
nx_clarity.nx source
↩ module page · 35 lines · 2112 B
1// nx_clarity.nx -- CLARITY = human-comprehension efficiency (operator 2026-06-22: "efficiency is energy clarity aka
2// can a person understand all those"). Efficiency isn't only machine cost (bytes/requests/ENERGY) -- it's whether a
3// PERSON can understand the thing without a manual; unclear output wastes human energy, so it's inefficient. This
4// measures "can a person understand all those" for any text/output, customer-facing OR internal: readable sentences +
5// self-describing words (not cryptic codes) + scannable structure. REUSE: nx_brand_voice (bv_longest_sentence_words).
6// license_tier: ORIGINAL
7import "nx_syscalls.nx"
8import "nx_brand_voice.nx"
9import "nx_brand_tokens.nx"
10
11// count runs of >=3 consecutive letters = "real words" (distinguishes plain language from cryptic codes/IDs).
12func cl_word_count(text: *u8, n: i64) -> i64 {
13 var c: i64 = 0; var i: i64 = 0; var run: i64 = 0
14 while i < n {
15 let ch: i64 = text[i] as i64
16 var letter: i64 = 0
17 if ch >= 65 { if ch <= 90 { letter = 1 } }
18 if ch >= 97 { if ch <= 122 { letter = 1 } }
19 if letter == 1 { run = run + 1 } else { if run >= 3 { c = c + 1 } run = 0 }
20 i = i + 1
21 }
22 if run >= 3 { c = c + 1 }
23 return c
24}
25// self-describing: enough real words that a person reads meaning, not a bare code line (0x3F|E2|0).
26func cl_self_describing(text: *u8, n: i64) -> i64 { if cl_word_count(text, n) >= 3 { return 1 } return 0 }
27// readable: the longest sentence is within a human-friendly word budget.
28func cl_readable(text: *u8, n: i64, max: i64) -> i64 { if bv_longest_sentence_words(text, n) <= max { return 1 } return 0 }
29// scannable: has headings (structure a person can skim).
30func cl_structured(html: *u8, n: i64) -> i64 { if bt_find(html, n, "<h1" as *u8, 3) >= 0 { return 1 } if bt_find(html, n, "<h2" as *u8, 3) >= 0 { return 1 } return 0 }
31// "can a person understand all those": readable AND self-describing.
32func cl_can_understand(text: *u8, n: i64, max: i64) -> i64 {
33 if cl_readable(text, n, max) == 1 { if cl_self_describing(text, n) == 1 { return 1 } }
34 return 0
35}