Coderabbitai/docstrings/4f5a1ed

lib/hypatia/cli.ex

@@ -307,18 +307,27 @@ defmodule Hypatia.CLI do
   # ─── Finding collection across rule modules ──────────────────────────
 
   @doc """
-  Run the named rule modules against `repo_path` and return unsuppressed findings
-  normalised as `%{rule_module, type, severity, file, reason, action}` maps.
-  Content-pattern findings also include their one-based source `line`. Public so
-  the RSR conformance oracle can delegate content-scan criteria to the live
-  scanners rather than reimplement per-file detection.
+Runs the selected rule modules against `repo_path` and returns normalized
+finding maps. Each map includes `rule_module`, `type`, `severity`, `file`,
+`reason`, and `action`; line-aware findings may also include `line`.
+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.
 
   `rules` is a list of module atoms (for example, `[:content_patterns,
   :structural_drift]`). GitHub alert modules (`:dependabot_alerts`,
   `:secret_scanning_alerts`, and `:code_scanning_alerts`) require network access
   and credentials; when unavailable, they write a warning to standard error and
   contribute no findings.
   """
+  @spec collect_findings(String.t(), [atom()]) :: [map()]
   def collect_findings(repo_path, rules) do
     results = []
 

lib/rules/cicd_rules.ex

@@ -808,9 +808,15 @@ defmodule Hypatia.Rules.CicdRules do
     * Inline pragma — `hypatia:ignore <rule_id>` on a matching line or the
       immediately preceding line suppresses that finding.
 
-  Returns findings with `rule`, `severity`, `reason`, `file`, `line`, and
-  `match` fields. File paths are relative to `repo_path`, and line numbers are
-  one-based.
+  Activates these previously-dormant rules: :innerhtml_usage,
+  :eval_in_shell, :download_then_run_shell, :hardcoded_tmp,
+  :template_placeholder, :deno_all_perms, :v_build_in_ci (#383),
+  :npx_in_workflow (#383), :http_in_docs (#383), and
+  :install_without_frozen_lockfile.
+
+  Returns a list of findings:
+    [%{rule: :rule_id, severity: "medium", reason: "...", file: "rel/path",
+       line: N, match: "..."}]
   """
   def scan_content_patterns(repo_path) do
     repo_name = Path.basename(repo_path)