Merge remote-tracking branch 'origin/claude/new-session-th4e9w-clippy' into claude/new-session-th4e9w-readiness

Author: claude

src/aggregate/proven_tests.rs

@@ -119,7 +119,10 @@ impl ReportTier {
 impl FromStr for ProvenTestsReport {
     type Err = anyhow::Error;
 
-    /// Parse a run report from JSON text.
+    /// Parse a run report from JSON text, requiring schema version 1.
+    ///
+    /// # Errors
+    /// Returns JSON deserialisation errors or an error if `schema_version` is not 1.
     fn from_str(text: &str) -> Result<Self> {
         let report: ProvenTestsReport =
             serde_json::from_str(text).context("parsing proven-tests run report")?;
@@ -134,7 +137,11 @@ impl FromStr for ProvenTestsReport {
 }
 
 impl ProvenTestsReport {
-    /// Parse a run report from a file path.
+    /// Read a UTF-8 JSON run report from `path` and parse it as schema version 1.
+    ///
+    /// # Errors
+    /// Returns file read errors (including invalid UTF-8), JSON deserialisation
+    /// errors or an error if `schema_version` is not 1.
     pub fn from_path(path: &Path) -> Result<Self> {
         let text =
             std::fs::read_to_string(path).with_context(|| format!("reading {}", path.display()))?;

src/assail/analyzer.rs

@@ -263,18 +263,16 @@ static RE_HARDCODED_SECRET: OnceLock<Regex> = OnceLock::new();
 /// Does not handle OCaml `(* *)` or Forth `\` — edge cases for later.
 static RE_TODO_COMMENT: OnceLock<Regex> = OnceLock::new();
 
-/// Heuristic: is the `malloc` on `lines[idx]` NULL-checked within a short
-/// window of following lines?
+/// Heuristically recognise a null check for the allocation on `lines[idx]`.
 ///
-/// An "UncheckedAllocation" finding should only fire when the result is *not*
-/// guarded. This recognises the common C idioms (`if (p == NULL)`,
-/// `if (!p)`, `if (p == nullptr)`) on the lvalue assigned from `malloc`.
+/// Searches the allocation line and up to six following lines for `NULL` or
+/// `nullptr` alongside the assigned identifier, or an `if` line containing `!`
+/// immediately followed by that identifier. If no identifier can be extracted,
+/// any `NULL` or `nullptr` substring in the window suffices. Substring matches
+/// do not establish that the allocation is guarded.
 ///
-/// Deliberately conservative to avoid false negatives in a security scanner:
-/// a site is treated as checked only on a clear NULL-guard signal that
-/// references the allocated variable (or, when no lvalue can be parsed, any
-/// NULL/nullptr token in the window). Genuinely-unchecked allocations — the
-/// real finding — are still reported.
+/// # Panics
+/// Panics if the zero-based `idx` is outside `lines`.
 fn c_alloc_result_is_null_checked(lines: &[&str], idx: usize) -> bool {
     let line = lines[idx];
     // Parse the lvalue assigned from malloc: the last identifier left of '='.

src/diagnostics.rs

@@ -11,6 +11,12 @@ const HYPATIA_ENV: &str = "HYPATIA_API_KEY";
 const GITBOT_FLEET_ENV: &str = "GITBOT_FLEET_ENDPOINT";
 const PANICBOT_DIRECTIVE_PATH: &str = ".machine_readable/bot_directives/panicbot.scm";
 
+/// Print readiness checks using `manifest`, paths relative to the current
+/// working directory and the configured integration environment variables.
+///
+/// # Errors
+/// Returns an error after printing all results if any check has error severity.
+/// Warnings alone do not cause failure.
 pub fn run_self_diagnostics(manifest: &Manifest) -> Result<()> {
     println!("panic-attack self-diagnostics");
 

src/report/gui.rs

@@ -120,6 +120,9 @@ impl ReportGui {
 }
 
 impl App for ReportGui {
+    /// Render the file loader, navigation and selected report tab.
+    /// A load-button click or Enter after the path field loses focus attempts
+    /// to read the specified JSON file, updating the viewer or its status message.
     fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut Frame) {
         egui::Panel::top("header").show(ui, |ui| {
             ui.horizontal(|ui| {

src/storage/mod.rs

@@ -229,7 +229,10 @@ pub struct MigrationSemantic {
     pub snapshot_label: Option<String>,
 }
 
-/// Build a VerisimDB hexad from an assault report
+/// Build a VerisimDB hexad from an assault report.
+///
+/// # Errors
+/// Propagates errors from serialising the report into its JSON document.
 fn build_hexad(report: &AssaultReport) -> Result<PanicAttackHexad> {
     let now = Utc::now();
     let id = format!(
@@ -375,6 +378,9 @@ pub fn persist_report(
 ///
 /// Unlike single-repo hexads which wrap an AssaultReport, assemblyline
 /// hexads capture the batch scan results across many repos.
+///
+/// # Errors
+/// Propagates errors from serialising the report into its JSON document.
 fn build_assemblyline_hexad(
     report: &crate::assemblyline::AssemblylineReport,
 ) -> Result<PanicAttackHexad> {
@@ -492,13 +498,13 @@ fn severity_label(severity: &crate::types::Severity) -> &'static str {
     }
 }
 
-/// Build one hexad per `WeakPoint` across all repo results in an
-/// assemblyline report (issue #33 S1).
+/// Build one hexad per unsuppressed `WeakPoint` across repo results with an
+/// AssailReport in an assemblyline report (issue #33 S1).
 ///
 /// Subject identity lives in `semantic.finding.finding_id`; each emitted
-/// hexad's top-level `id` remains per-run-unique so two runs of the same
-/// finding produce two distinct hexad files (the join key is the
-/// `finding_id`, not the hexad id).
+/// hexad's top-level `id` includes a millisecond timestamp and repo/finding
+/// indices. IDs are distinct within a call but may repeat across calls in
+/// the same millisecond; use `finding_id` as the join key.
 ///
 /// `run_id` is shared across every finding-hexad in this run and stamped
 /// into both `first_seen_run` and `last_seen_run` (S1 has no prior-run
@@ -662,10 +668,10 @@ fn derive_crosslang_interactions_for_report(
 /// repo in an assemblyline report (issue #33 kanren-crosslang follow-up).
 ///
 /// Subject identity lives in `semantic.crosslang.interaction_id`; the
-/// top-level hexad `id` is per-run-unique so two runs of the same
-/// interaction produce two distinct hexad files (the join key is the
-/// `interaction_id`, not the hexad id). Returns an empty `Vec` when the
-/// report has no AssailReport-bearing results or no derivable interactions.
+/// top-level hexad `id` includes a millisecond timestamp and repo/interaction
+/// indices. IDs are distinct within a call but may repeat across calls in
+/// the same millisecond; use `interaction_id` as the join key. Returns an empty
+/// `Vec` when the report has no AssailReport-bearing results or no derivable interactions.
 pub fn build_crosslang_hexads(
     report: &crate::assemblyline::AssemblylineReport,
 ) -> Result<Vec<PanicAttackHexad>> {
@@ -772,9 +778,10 @@ const HEXAD_FILE_READ_LIMIT: u64 = 16 * 1024 * 1024;
 
 /// Build a campaign-state hexad for one lifecycle event (issue #33 S2).
 ///
-/// Append-only: each call produces a fresh hexad with a unique id. The
-/// `finding_id` is carried as the semantic subject so the newest hexad
-/// per finding is the current state.
+/// The id is derived from the current millisecond timestamp, so calls in the
+/// same millisecond can produce the same id. This only constructs a hexad;
+/// it does not write to storage. The `finding_id` is carried as the semantic
+/// subject so stored events can be grouped by finding.
 pub fn build_campaign_hexad(semantic: CampaignSemantic) -> PanicAttackHexad {
     let now = Utc::now();
     let hexad_id = format!(