From d351ba5aa4a9404779639449e6eeb30dc58693cd Mon Sep 17 00:00:00 2001
From: Metbcy <Amirbredy1@gmail.com>
Date: Sun, 17 May 2026 21:27:11 +0000
Subject: [PATCH] chore: align json.rs panic msg and document module size
 budget
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two small hygiene items surfaced during a panic-audit pass over
src/.

1. src/render/json.rs:46 used a terse '.expect("serialize JSON")'
   while the equivalent invariant in src/vex.rs and src/render/sarif.rs
   uses the self-documenting form ('invariant: serde_json::to_string_pretty
   cannot fail on a Value built from owned data with string keys').
   The terse message is misleading on a panic — a reader would think
   serialization actually failed, when the panic is a should-never-happen
   guard on a structurally-validated input. Align the message so all
   three call sites read the same way.

   Verified: 'cargo test --lib render::json' still green (5/5).

2. docs/src/architecture.md gains a 'Module size budget' section
   mirroring the existing 'Binary size budget' pattern:
     - Soft cap: ≤ 1000 LOC per src/*.rs (incl. embedded test mod)
     - Hard cap: ≤ 1500 LOC (split before adding behavior)
     - Audit command + waiver path

   PR #44 (markdown.rs split) sets the reference shape. Current
   offenders (vex.rs 1441, run.rs 1326, render/sarif.rs 1205,
   enrich/typosquat.rs 1088, baseline.rs 1072) are now greppable
   candidates for follow-up refactor PRs; #31 is the next one in
   the pipeline.

No production code paths change in this commit.
---
 docs/src/architecture.md | 15 +++++++++++++++
 src/render/json.rs       |  3 ++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/src/architecture.md b/docs/src/architecture.md
index d349a18..fae6596 100644
--- a/docs/src/architecture.md
+++ b/docs/src/architecture.md
@@ -264,3 +264,18 @@ beyond what `ureq` already brings.
 - **Current** (v0.9.6): ~3.4 MB.
 - **Audit**: `cargo bloat --release --crates -n 20` periodically to
   confirm no unexpected dep-tree growth.
+
+## Module size budget
+
+- **Soft cap**: ≤ 1000 LOC per file in `src/` (incl. `#[cfg(test)] mod tests`).
+  At ~1000 LOC the file usually contains more than one cohesive concern
+  and review attention starts skipping the middle.
+- **Hard cap**: ≤ 1500 LOC. Past this, split before adding new behavior;
+  PR #44 (markdown.rs → markdown/{mod,components,vulns,...}.rs) is the
+  reference shape for how the split should look.
+- **Audit**: `find src -name '*.rs' -exec wc -l {} \; | sort -rn | head`
+  during release prep. Any file past the soft cap goes into the next
+  refactor cycle's candidate list; any file past the hard cap blocks
+  the release until split or explicitly waived in the changelog.
+- Tests-only files (`tests/**`) are exempt — large integration tests
+  are easier to read as one file than as a maze of helpers.
diff --git a/src/render/json.rs b/src/render/json.rs
index 880417c..bd6ae57 100644
--- a/src/render/json.rs
+++ b/src/render/json.rs
@@ -43,7 +43,8 @@ pub fn render(cs: &ChangeSet, e: &Enrichment) -> String {
         clippy::expect_used,
         reason = "invariant: serde_json::to_string_pretty cannot fail on a Value built from owned data with string keys"
     )]
-    serde_json::to_string_pretty(&combined).expect("serialize JSON")
+    serde_json::to_string_pretty(&combined)
+        .expect("invariant: serde_json::to_string_pretty cannot fail on a Value built from owned data with string keys")
 }
 
 #[cfg(test)]