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

Author: claude

src/aggregate/mod.rs

@@ -394,6 +394,11 @@ pub fn run(config: AggregateConfig) -> Result<AggregateReport> {
     })
 }
 
+/// Write the aggregate report as pretty-printed JSON, creating parent directories
+/// and replacing any existing file at `path`.
+///
+/// # Errors
+/// Returns directory creation, JSON serialisation and file write errors.
 pub fn write_report(report: &AggregateReport, path: &Path) -> Result<()> {
     if let Some(parent) = path.parent() {
         if !parent.as_os_str().is_empty() {
@@ -493,6 +498,8 @@ fn has_metavar_hole(text: &str) -> bool {
     false
 }
 
+/// Look for case-sensitive proof or declaration substrings as a closure heuristic;
+/// a match does not verify that the text contains a valid proof.
 fn has_proof_keyword(text: &str) -> bool {
     const KW: &[&str] = &[
         "theorem", "lemma", "Theorem", "Lemma", "Proof", "proof", "where", ":=", "data ", "record ",
@@ -606,6 +613,10 @@ fn scan_covers(text: &str) -> Vec<Coverage> {
 
 /// Parse `[claim:]kind:value`, e.g. `sound:category:UnsafeCode`,
 /// `safe:file:src/foo.rs`, `category:PanicPath`, `free:my-lemma`.
+///
+/// A bare token other than `safe` or `sound` becomes free-form coverage with an
+/// unspecified claim. Returns `None` for an empty first field, an unrecognised
+/// kind or an unsupported field layout. Values are retained without trimming.
 pub fn parse_coverage_spec(spec: &str) -> Option<Coverage> {
     let mut parts: Vec<&str> = spec.splitn(3, ':').collect();
     if parts.is_empty() || parts[0].is_empty() {
@@ -692,6 +703,7 @@ fn summarise(findings: &[FindingLite]) -> FindingSummary {
     }
 }
 
+/// Count findings selected by the coverage annotation; free-form coverage matches none.
 fn count_matching(findings: &[FindingLite], cov: &Coverage) -> usize {
     findings.iter().filter(|f| matches_coverage(f, cov)).count()
 }

src/assail/analyzer.rs

@@ -941,6 +941,10 @@ impl Analyzer {
     // Original language analyzers
     // ============================================================
 
+    /// Accumulate Rust statistics and append heuristic findings for `file_path`.
+    /// Dangerous-pattern checks exclude string contents, comments, `cfg`-selected
+    /// test bodies and `should_panic` bodies. Panic counts and findings also exclude
+    /// test paths and build scripts.
     fn analyze_rust(
         &self,
         content: &str,
@@ -1767,6 +1771,9 @@ impl Analyzer {
         false
     }
 
+    /// Accumulate C/C++ statistics and append heuristic findings for `file_path`.
+    /// Unchecked malloc findings include one-based line numbers for suppression
+    /// and omit allocations with a recognised nearby null check.
     fn analyze_c_cpp(
         &self,
         content: &str,
@@ -2012,6 +2019,8 @@ impl Analyzer {
         Ok(())
     }
 
+    /// Accumulate Go statistics and append heuristic concurrency, unsafe pointer,
+    /// command execution and cryptography findings located at `file_path`.
     fn analyze_go(
         &self,
         content: &str,
@@ -2141,6 +2150,8 @@ impl Analyzer {
         Ok(())
     }
 
+    /// Accumulate Python I/O and threading counts and append heuristic loop,
+    /// code execution, deserialisation, command and cryptography findings for `file_path`.
     fn analyze_python(
         &self,
         content: &str,
@@ -3168,6 +3179,9 @@ impl Analyzer {
         }
     }
 
+    /// Accumulate OCaml statistics and append heuristic findings for `file_path`.
+    /// Classify `Obj.magic` as proof drift when Coq extraction markers are present,
+    /// or as unsafe type coercion otherwise.
     fn analyze_ocaml(
         &self,
         content: &str,
@@ -4320,6 +4334,8 @@ impl Analyzer {
         Ok(())
     }
 
+    /// Accumulate Odin operation counts and append a Medium unsafe-code finding
+    /// at `file_path` when `rawptr` occurs in the content.
     fn analyze_odin(
         &self,
         content: &str,
@@ -4498,6 +4514,9 @@ impl Analyzer {
     // Config languages (Nickel, Nix)
     // ============================================================
 
+    /// Accumulate Nix/Nickel I/O counts and append Nix command and unpinned-flake findings.
+    /// Uses `file_path` for file-type checks, finding locations and the sibling
+    /// `flake.lock` lookup on disk.
     fn analyze_config(
         &self,
         content: &str,
@@ -4602,6 +4621,9 @@ impl Analyzer {
     // Shell scripting
     // ============================================================
 
+    /// Accumulate shell I/O counts and append heuristic command, permission and
+    /// temporary-path findings for `file_path`. Unquoted expansion findings require
+    /// more than 20 `$VAR` matches after quoted string contents are removed.
     fn analyze_shell(
         &self,
         content: &str,
@@ -5035,6 +5057,8 @@ impl Analyzer {
     // Cross-language security checks (run on ALL files)
     // ============================================================
 
+    /// Append heuristic protocol, hardcoded secret and excessive comment-marker
+    /// findings located at `file_path`, independently of the detected language.
     fn analyze_cross_language(
         &self,
         content: &str,

src/assail/mod.rs

@@ -402,21 +402,22 @@ pub fn apply_suppression(report: &mut AssailReport) {
     report.suppressed_count = count;
 }
 
-/// v2.5.5 context-aware FP suppression pass — applies four checks per
+/// v2.5.5 context-aware FP suppression pass — applies three checks per
 /// finding:
 ///   1. Inline `panic-attack: accepted` marker on the same or
-///      preceding line ([[comment_marker]]).
+///      preceding line, when `wp.line` is known ([[comment_marker]]).
 ///   2. PanicPath finding in a TestOnly or Doc test_context
 ///      ([[test_context]]).
 ///   3. UnsafeFFI finding where the file's [[ffi_kind]] is
 ///      `BuildSystem` or `TestMock` (audit-accepted by default).
-///   4. (jit_context wire-up handled inline in analyzer.rs:1117..1129
-///      already; not duplicated here.)
 ///
-/// Sets `wp.test_context` for every finding with a known file path so
+/// JIT context handling remains inline in analyzer.rs:1117..1129.
+///
+/// Fills missing `wp.test_context` for findings with a known file path so
 /// downstream audit consumers can render it. Returns the number of
 /// findings newly flipped from `suppressed=false` to `suppressed=true`
 /// (already-suppressed findings are NOT re-counted).
+/// File read errors disable marker checks and use path-only context classification.
 pub fn apply_v255_context_suppression(report: &mut AssailReport) -> usize {
     use crate::comment_marker;
     use crate::ffi_kind::FfiKind;

src/assay/mod.rs

@@ -277,6 +277,11 @@ pub fn run(config: AssayConfig) -> Result<AssayReport> {
     })
 }
 
+/// Write the assay report as pretty-printed JSON, creating parent directories
+/// and replacing any existing file at `path`.
+///
+/// # Errors
+/// Returns directory creation, JSON serialisation and file write errors.
 pub fn write_report(report: &AssayReport, path: &Path) -> Result<()> {
     if let Some(parent) = path.parent() {
         if !parent.as_os_str().is_empty() {
@@ -348,6 +353,20 @@ pub struct AssimilateConfig {
     pub dry_run: bool,
 }
 
+/// Apply selected proven-module substitutions and return provenance records and notes.
+///
+/// `apply_all` selects offered candidates; otherwise `candidate_id` is required.
+/// Already-applied candidates are skipped. The `from` override requires exactly
+/// one selected candidate. Call sites are returned for manual rewiring.
+///
+/// Unless `dry_run` is set, copy replacement files, preserve existing `.orig`
+/// backups and write provenance under the target's `.assimilated/` directory.
+/// Dry runs still resolve and hash sources and existing destination files.
+///
+/// # Errors
+/// Returns survey errors, invalid candidate or source selection errors, and errors
+/// from hashing, directory creation, file copying or provenance serialisation/writing.
+/// Earlier file changes remain in place if a later operation fails.
 pub fn assimilate(config: AssimilateConfig) -> Result<AssimilationOutcome> {
     let assay = run(AssayConfig {
         target: config.target.clone(),

src/diagnostics.rs

@@ -193,8 +193,11 @@ fn check_watcher(label: &'static str, env_key: &str) -> Diagnostic {
 /// Verifies:
 ///   1. Bot directives file exists at `.machine_readable/bot_directives/panicbot.scm`
 ///   2. JSON output contract: AssailReport serialises with the fields panicbot expects
-///      (`program_path`, `weak_points`, `language`, `statistics`)
+///      (`program_path`, `weak_points`, `language`)
 ///   3. WeakPointCategory and Severity serialise in PascalCase (no serde rename_all)
+///
+/// Failed JSON checks, including serialisation errors, yield an error diagnostic;
+/// missing directives alone yield a warning.
 fn check_panicbot_readiness() -> Diagnostic {
     let directive_path = Path::new(PANICBOT_DIRECTIVE_PATH);
     let has_directives = directive_path.is_file();

src/ffi_kind.rs

@@ -87,6 +87,7 @@ fn is_build_system_path(p: &str) -> bool {
         || p.contains("build.cargo/")
 }
 
+/// Recognise test mock paths by case-sensitive test-scope and mock/stub substrings.
 fn is_test_mock_path(p: &str) -> bool {
     // Test mocks live under tests/ AND have "mock" or "stub" in the
     // path. Plain test files are still RuntimeAbi if they call the
@@ -120,9 +121,11 @@ fn is_runtime_abi_path(p: &str) -> bool {
 /// project's pre-approved FFI boundary audit (typically
 /// `audits/audit-ffi-unsafe.md`).
 ///
-/// Implementation note: this is a placeholder that parses the audit
-/// file when present and returns false otherwise. Wire-in to the
-/// analyzer happens in the follow-up PR.
+/// Reads the supplied `audit_text` without accessing the filesystem. Section
+/// headings `Approved boundaries`, `Approved FFI boundaries` and `Pre-approved
+/// boundaries` are recognised case-insensitively at Markdown level two. Within
+/// them, the first token after an optional list marker is compared exactly with
+/// `file_path`, ignoring surrounding backticks. Returns false if no token matches.
 pub fn is_audited_boundary(audit_text: &str, file_path: &str) -> bool {
     // The audit file's convention is a `## Approved boundaries` section
     // with a markdown list of `- file/path/here.zig — rationale` lines.

src/jit_context.rs

@@ -81,6 +81,7 @@ pub fn classify_rust(content: &str) -> JitContext {
     }
 }
 
+/// Recognise Cranelift imports or JIT API usage by case-sensitive substring matches.
 fn is_cranelift(content: &str) -> bool {
     content.contains("cranelift_jit::JITModule")
         || content.contains("cranelift_module::Module")
@@ -113,9 +114,10 @@ fn is_javascript_embedding(content: &str) -> bool {
         || (content.contains("v8::") && content.contains("Function::call"))
 }
 
-/// True if a `mem::transmute` (or `transmute_copy`) in this content
-/// targets a function-pointer type. Pattern-matches the standard
-/// turbofish forms and let-binding forms documented in
+/// Look for `transmute` syntax suggesting a function-pointer target.
+/// Recognises selected turbofish forms or a function-pointer annotation occurring
+/// anywhere alongside a `transmute(` call, without verifying they belong to the
+/// same expression. `transmute_copy` is not recognised. See the related forms in
 /// `src/assail/analyzer.rs:1110..1129`.
 pub fn transmute_targets_fn_ptr(content: &str) -> bool {
     // Turbofish forms — unambiguous.

src/main.rs

@@ -1365,6 +1365,13 @@ fn main() -> Result<()> {
     result
 }
 
+/// Parse process arguments and execute the selected command, including its output
+/// and requested persistence. Default manifest settings are used if loading fails.
+/// Argument parsing exits the process for help or invalid CLI syntax.
+///
+/// # Errors
+/// Returns command validation errors and propagates I/O, serialisation and
+/// operation errors that are not handled by a command-specific fallback.
 fn run_main() -> Result<()> {
     let cli = Cli::parse();
     let manifest = match Manifest::load_default() {

src/scan/cargodeny.rs

@@ -112,7 +112,15 @@ fn code_to_category(code: &str) -> WeakPointCategory {
     }
 }
 
-/// Run cargo-deny check and parse output
+/// Run `cargo deny check` in the configured workspace and return its diagnostic findings.
+///
+/// Standard output must be UTF-8 JSON matching `DenyOutput`, regardless of
+/// `config.format`. A non-zero exit status still yields findings if parsing succeeds.
+/// Missing severity and code fields default to Medium and Advisory respectively.
+/// `config.deny_toml` is currently ignored.
+///
+/// # Errors
+/// Returns process execution errors, invalid UTF-8 errors and JSON deserialisation errors.
 pub fn run_cargo_deny(config: &CargoDenyConfig) -> Result<Vec<WeakPoint>> {
     let workspace_root = &config.workspace_root;
 
@@ -257,7 +265,13 @@ impl From<WeakPoint> for CargoDenyWeakPoint {
     }
 }
 
-/// Parse cargo-deny SARIF output (alternative to JSON)
+/// Convert cargo-deny SARIF results into findings, using only the first location
+/// of each result. Missing levels default to Medium severity; missing or
+/// unrecognised rule IDs default to Advisory.
+///
+/// # Errors
+/// Returns JSON parsing errors, or an error if `runs` or any run's `results` is
+/// absent or is not an array. Empty `runs` and `results` arrays are valid.
 #[cfg(feature = "sarif")]
 pub fn parse_sarif_output(sarif_json: &str) -> Result<Vec<WeakPoint>> {
     use serde_json::Value;
@@ -344,7 +358,12 @@ pub fn parse_sarif_output(sarif_json: &str) -> Result<Vec<WeakPoint>> {
     Ok(weak_points)
 }
 
-/// High-level function to scan a workspace and emit cargo-deny weak points
+/// Scan a workspace with cargo-deny's JSON defaults and return diagnostic findings.
+/// The `deny_toml` argument currently has no effect.
+///
+/// # Errors
+/// Propagates execution, UTF-8 decoding and JSON deserialisation errors from
+/// [`run_cargo_deny`]. A non-zero cargo-deny exit status alone is not an error.
 pub fn scan_workspace(workspace_root: &Path, deny_toml: Option<&Path>) -> Result<Vec<WeakPoint>> {
     let config = CargoDenyConfig {
         workspace_root: workspace_root.to_path_buf(),