Add docstrings to satisfy CodeRabbit coverage on PR #918.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: northdpole

application/utils/external_project_parsers/parsers/pci_dss.py

@@ -23,6 +23,7 @@
 
 
 def _parse_float_env(name: str, default: float) -> float:
+    """Read a float from an environment variable, falling back on invalid values."""
     raw = os.environ.get(name, "").strip()
     if not raw:
         return default
@@ -34,6 +35,7 @@ def _parse_float_env(name: str, default: float) -> float:
 
 
 def _parse_float_tuple_env(name: str, default: tuple[float, ...]) -> tuple[float, ...]:
+    """Read a comma-separated float tuple from env, falling back on invalid values."""
     raw = os.environ.get(name, "").strip()
     if not raw:
         return default
@@ -46,6 +48,7 @@ def _parse_float_tuple_env(name: str, default: tuple[float, ...]) -> tuple[float
 
 
 def _parse_str_tuple_env(name: str, default: tuple[str, ...]) -> tuple[str, ...]:
+    """Read a comma-separated string tuple from env, falling back when empty."""
     raw = os.environ.get(name, "").strip()
     if not raw:
         return default

application/utils/external_project_parsers/parsers/secure_headers.py

@@ -53,6 +53,7 @@ def entry(self, section: str, hyperlink: str, tags: List[str]) -> defs.Standard:
     def resolve_cre_external_id(
         self, cache: db.Node_collection, external_id: str
     ) -> tuple[list[defs.CRE], str]:
+        """Resolve a markdown CRE id, applying legacy remaps when needed."""
         candidates = [external_id]
         remapped = LEGACY_CRE_ID_REMAP.get(external_id)
         if remapped and remapped not in candidates:

application/utils/gap_analysis.py

@@ -117,12 +117,14 @@ def get_next_id(step, previous_id):
 
 
 def _link_type_to_path_relationship(ltype: defs.LinkTypes) -> str:
+    """Map a link type to the path relationship label stored in GA cache rows."""
     if ltype == defs.LinkTypes.AutomaticallyLinkedTo:
         return "AUTOMATICALLY_LINKED_TO"
     return "LINKED_TO"
 
 
 def _opencre_overlap_link_sort_key(link: defs.Link) -> int:
+    """Prefer manual CRE links over automatic links when ordering overlap paths."""
     if link.ltype == defs.LinkTypes.LinkedTo:
         return 0
     if link.ltype == defs.LinkTypes.AutomaticallyLinkedTo:
@@ -136,6 +138,7 @@ def _build_direct_link_path(
     *,
     ltype: defs.LinkTypes = defs.LinkTypes.LinkedTo,
 ) -> Dict[str, Any]:
+    """Build a single-hop GA path between two documents with the given link type."""
     segment_start = start_document.shallow_copy()
     if segment_start.doctype != defs.Credoctypes.CRE.value:
         segment_start.id = ""
@@ -160,6 +163,7 @@ def _add_direct_link_result(
     *,
     ltype: defs.LinkTypes = defs.LinkTypes.LinkedTo,
 ) -> None:
+    """Insert one direct link path into grouped GA results, skipping duplicates."""
     shared_paths = grouped_paths.setdefault(
         start_document.id,
         {
@@ -244,6 +248,7 @@ def opencre_direct_pairs(standard_names: List[str]) -> List[List[str]]:
 
 
 def missing_opencre_direct_pairs(collection: Any) -> List[List[str]]:
+    """Return OpenCRE-directed standard pairs that are not yet cached."""
     missing: List[List[str]] = []
     for pair in opencre_direct_pairs(collection.standards()):
         cache_key = make_resources_key(pair)

scripts/compute_pci_dss_cre_mappings.py

@@ -55,6 +55,7 @@
 
 
 def _configure_llm_env() -> None:
+    """Set default embedding model env vars for offline PCI mapping runs."""
     embed_model = os.environ.get("CRE_EMBED_MODEL")
     if not embed_model:
         vertex_embed = os.environ.get(
@@ -66,6 +67,7 @@ def _configure_llm_env() -> None:
 
 
 def fetch_pci_rows(url: str = PCI_SHEET_CSV_URL) -> List[Dict[str, str]]:
+    """Download PCI DSS spreadsheet rows that include a control id."""
     with urllib.request.urlopen(url, timeout=120) as resp:
         raw = resp.read().decode("utf-8-sig")
     reader = csv.DictReader(io.StringIO(raw))
@@ -80,6 +82,7 @@ def resolve_with_method(
     cache,
     control_embedding: List[float],
 ) -> tuple[Optional[defs.CRE], str, Optional[float]]:
+    """Resolve one PCI control embedding using the staged PCI DSS linker."""
     for threshold in PCI_DSS_CRE_SIMILARITY_THRESHOLDS:
         match = prompt.get_id_of_most_similar_cre_paginated(
             control_embedding, similarity_threshold=threshold
@@ -112,6 +115,7 @@ def compute_mappings(
     *,
     limit: Optional[int] = None,
 ) -> List[Dict[str, Any]]:
+    """Embed PCI rows and resolve CRE links, returning per-control mapping records."""
     prompt = prompt_client.PromptHandler(cache)
     mappings: List[Dict[str, Any]] = []
     total = len(rows) if limit is None else min(limit, len(rows))
@@ -155,6 +159,7 @@ def compute_mappings(
 
 
 def main() -> int:
+    """CLI entrypoint for computing PCI DSS to CRE mapping JSON."""
     parser = argparse.ArgumentParser(description="Compute PCI DSS → CRE mappings")
     parser.add_argument(
         "--cache-file",