From 5a578574b1f779029be082289f846158a4cb57e9 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Fri, 4 Sep 2026 09:14:26 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`feat/sc?=
 =?UTF-8?q?anner-derived-content-rules`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @hyperpolymath.

* https://github.com/hyperpolymath/hypatia/pull/753#issuecomment-5538253282

The following files were modified:

* `lib/hypatia/cli.ex`
---
 lib/hypatia/cli.ex | 19 ++++++++++++-------
 1 file changed, 12 insertions(+), 7 deletions(-)

diff --git a/lib/hypatia/cli.ex b/lib/hypatia/cli.ex
index 72f4c7f0..4f4d182a 100644
--- a/lib/hypatia/cli.ex
+++ b/lib/hypatia/cli.ex
@@ -301,14 +301,19 @@ defmodule Hypatia.CLI do
   # ─── Finding collection across rule modules ──────────────────────────
 
   @doc """
-  Run the named rule modules against `repo_path` and return normalized findings
-  (`%{rule_module, type, severity, file, reason, action}`). Public so the RSR
-  conformance oracle can delegate content-scan criteria to the live scanners
-  rather than reimplement per-file detection. `rules` is a list of module atoms
-  (e.g. `[:cicd_rules, :structural_drift]`); GitHub-API modules
-  (`:dependabot_alerts`, `:secret_scanning_alerts`, `:code_scanning_alerts`,
-  `:scorecard`) require network + token and return nothing offline.
+  Runs the selected rule modules against a repository and produces findings in a
+  common map format. Findings covered by configured suppressions are excluded.
+  
+  ## Parameters
+  
+    - repo_path: Path to the repository to scan.
+    - rules: Rule module identifiers to run.
+  
+  ## Returns
+  
+  A list of normalized finding maps.
   """
+  @spec collect_findings(String.t(), [atom()]) :: [map()]
   def collect_findings(repo_path, rules) do
     results = []