nx_librarian.nx source
↩ module page · 148 lines · 7353 B
1// nx_librarian.nx -- the DOCUMENTATION module of the Nishi Project Manager.
2//
3// The Nishi PM (executive sponsor: the operator) manages both PROJECT work
4// and DOCUMENTATION work; this module is the documentation half -- the
5// "librarian". It CATALOGS the information namespaces (docs, memory,
6// silicon charters), AUDITS their health (link-rot, V2/NISHIDOC metadata
7// compliance), and prints a nishi-doctor-style verdict the PM rolls up.
8// Sovereign + native x86 -- NO qemu, NO shell. It runs where the corpus
9// lives (the repo host), like nishi doctor and the dashboards.
10//
11// REUSES the existing audit engines verbatim (operator cardinal: never
12// reinvent -- most capabilities already exist):
13// nx_doc_xref -- backtick-aware [[X]] link-rot, dual-namespace
14// nx_doc_census -- the 7-axis V2/NISHIDOC compliance classifier
15// The only net-new code here is the probe->classify->verdict orchestration
16// (modeled on nx_doctor.nx) -- the same spine the PM's project-work half uses.
17//
18// **Quadrant:** REFERENCE (Diataxis) **Topic Type:** REFERENCE (DITA)
19// **Status:** DRAFT **Trust State:** WRITTEN_UNTESTED **Competitive State:** UNCLASSIFIED
20//
21// Status: V1. 2026-05-30.
22
23import "nx_syscalls.nx"
24import "nx_doc_xref.nx"
25import "nx_doc_census.nx"
26
27// ===== Verdict states + thresholds (Rule 11: named, not magic) ============
28const LIB_OK: i64 = 0
29const LIB_WARN: i64 = 1
30const LIB_FAIL: i64 = 2
31const LIB_ROT_WARN_PCT: i64 = 5 // link-rot >= 5% -> warn
32const LIB_ROT_FAIL_PCT: i64 = 15 // link-rot >= 15% -> fail
33const LIB_COMP_OK_PCT: i64 = 75 // compliance >= 75% -> ok (CONFIRMED band)
34const LIB_COMP_WARN_PCT: i64 = 50 // compliance >= 50% -> warn (INCONCLUSIVE band)
35const LIB_BLOB_CAP: i64 = 262144 // 256 KiB names blob for the dual-namespace walk
36const LIB_STRLEN_CAP: i64 = 8192
37
38// ===== Output helpers (modeled on nx_doctor.nx) ============
39func lib_strlen(s: *u8) -> i64 {
40 var n: i64 = 0
41 while n < LIB_STRLEN_CAP { if s[n] == (0 as u8) { return n } n = n + 1 }
42 return LIB_STRLEN_CAP
43}
44func lib_puts(s: *u8) -> i64 {
45 sys_write(1, s, lib_strlen(s))
46 return 0
47}
48func lib_putn(n: i64) -> i64 {
49 if n == 0 { sys_write(1, "0" as *u8, 1); return 0 }
50 var m: i64 = n
51 let d: *u8 = sys_mmap(24)
52 var k: i64 = 0
53 while m > 0 { d[k] = (0x30 + (m % 10)) as u8; m = m / 10; k = k + 1 }
54 var i: i64 = k - 1
55 while i >= 0 { let one: *u8 = sys_mmap(1); one[0] = d[i]; sys_write(1, one, 1); i = i - 1 }
56 return 0
57}
58func lib_sym(state: i64) -> i64 {
59 if state == LIB_OK { sys_write(1, "[OK]", 4); return 0 }
60 if state == LIB_WARN { sys_write(1, "[~~]", 4); return 0 }
61 sys_write(1, "[XX]", 4)
62 return 0
63}
64
65func main() -> i64 {
66 lib_puts("NISHI PROJECT MANAGER -- Librarian module (documentation health)\n" as *u8)
67 lib_puts("===============================================================\n" as *u8)
68 var problems: i64 = 0
69 var warns: i64 = 0
70
71 // Information namespaces (paths hardcoded V1, like the audit runners;
72 // the underlying walk_dir functions take the path as an argument).
73 let docs: *u8 = "/mnt/c/Users/elder/nishi-core/nxc2/docs" as *u8
74 let docs_n: i64 = lib_strlen(docs)
75 let mem: *u8 = "/mnt/c/Users/elder/.claude/projects/C--Users-elder/memory" as *u8
76 let mem_n: i64 = lib_strlen(mem)
77 let sil: *u8 = "/mnt/c/Users/elder/nishi-silicon" as *u8
78 let sil_n: i64 = lib_strlen(sil)
79
80 // ---- CATALOG: count each namespace (census n_total) ----
81 let dc: *NxDocCensusCounts = (sys_mmap(128)) as *NxDocCensusCounts
82 nx_doc_census_init(dc)
83 nx_doc_census_walk_dir(docs, docs_n, dc)
84 let mc: *NxDocCensusCounts = (sys_mmap(128)) as *NxDocCensusCounts
85 nx_doc_census_init(mc)
86 nx_doc_census_walk_dir(mem, mem_n, mc)
87 let scn: *NxDocCensusCounts = (sys_mmap(128)) as *NxDocCensusCounts
88 nx_doc_census_init(scn)
89 nx_doc_census_walk_dir(sil, sil_n, scn)
90
91 lib_puts("\n CATALOG (information namespaces)\n" as *u8)
92 lib_puts(" docs (nxc2/docs) ........... " as *u8); lib_putn(dc.n_total); lib_puts(" docs\n" as *u8)
93 lib_puts(" memory (cardinals/notes) ... " as *u8); lib_putn(mc.n_total)
94 if mc.n_total >= 512 { lib_puts("+ notes (census walker cap; V2 lifts it)\n" as *u8) } else { lib_puts(" notes\n" as *u8) }
95 lib_puts(" silicon charters ........... " as *u8); lib_putn(scn.n_total); lib_puts(" docs\n" as *u8)
96 lib_puts(" code / crawl / benchmarks .. cataloged by artifact_store / inverted-index / leaderboard\n" as *u8)
97
98 lib_puts("\n DOCUMENTATION HEALTH\n" as *u8)
99
100 // ---- V2 / NISHIDOC metadata compliance (docs; the V2 schema applies here) ----
101 // (census is silent -- summary only)
102 let comp_pct: i64 = nx_doc_census_pct_compliance(dc)
103 var comp_state: i64 = LIB_OK
104 if comp_pct < LIB_COMP_WARN_PCT { comp_state = LIB_FAIL; problems = problems + 1 } else {
105 if comp_pct < LIB_COMP_OK_PCT { comp_state = LIB_WARN; warns = warns + 1 }
106 }
107 lib_puts(" V2 compliance ..... " as *u8); lib_putn(comp_pct)
108 lib_puts("% full=" as *u8); lib_putn(dc.n_full_compliance)
109 lib_puts(" zero=" as *u8); lib_putn(dc.n_zero_compliance)
110 lib_puts(" " as *u8); lib_sym(comp_state); lib_puts("\n" as *u8)
111
112 // ---- link-rot: docs' [[X]] refs validated against docs + memory ----
113 // The reused xref walker prints each broken cross-ref as it goes -- that
114 // IS the "what to fix" rot ledger a librarian should surface, so we frame
115 // it rather than suppress it; the summary line follows.
116 lib_puts(" link-rot ledger (broken cross-references found) ->\n" as *u8)
117 let blob: *u8 = sys_mmap(LIB_BLOB_CAP)
118 let blob_n: i64 = nx_doc_xref_build_names_blob(mem, mem_n, blob, LIB_BLOB_CAP)
119 let xc: *NxDocXrefCounts = (sys_mmap(64)) as *NxDocXrefCounts
120 nx_doc_xref_counts_init(xc)
121 nx_doc_xref_walk_dir_dual(docs, docs_n, blob, blob_n, xc)
122 var rot_pct: i64 = 0
123 if xc.n_refs_total > 0 { rot_pct = (xc.n_refs_broken * 100) / xc.n_refs_total }
124 var rot_state: i64 = LIB_OK
125 if rot_pct >= LIB_ROT_FAIL_PCT { rot_state = LIB_FAIL; problems = problems + 1 } else {
126 if rot_pct >= LIB_ROT_WARN_PCT { rot_state = LIB_WARN; warns = warns + 1 }
127 }
128 lib_puts(" link-rot .......... " as *u8)
129 lib_putn(xc.n_refs_broken); lib_puts("/" as *u8); lib_putn(xc.n_refs_total)
130 lib_puts(" broken = " as *u8); lib_putn(rot_pct); lib_puts("% " as *u8)
131 lib_sym(rot_state); lib_puts("\n" as *u8)
132 lib_puts(" (orphans, dedup, staleness queued: nx_doc_inref + nx_simhash + mtime are built)\n" as *u8)
133
134 // ---- VERDICT (the PM roll-up the exec sponsor reads) ----
135 lib_puts("\n PM verdict: " as *u8)
136 lib_putn(problems); lib_puts(" failing, " as *u8); lib_putn(warns); lib_puts(" warning.\n" as *u8)
137 if problems == 0 {
138 if warns == 0 { lib_puts(" Documentation catalog healthy.\n" as *u8) }
139 if warns > 0 { lib_puts(" Catalog serviceable; metadata backfill recommended to reach CONFIRMED.\n" as *u8) }
140 }
141 if problems > 0 {
142 lib_puts(" Action: V2 metadata compliance is below the FALSIFIED threshold -- the\n" as *u8)
143 lib_puts(" highest-leverage doc work is backfilling the 7-axis header on zero-V2 docs.\n" as *u8)
144 }
145 if problems > 0 { return 2 }
146 if warns > 0 { return 1 }
147 return 0
148}