📝 Add docstrings to ops/ci-gates-and-qa-docs (#6)

Docstrings generation was requested by @shayancoin.

* #5 (comment)

The following files were modified:

* `backend/tests/test_error_envelopes.py`
* `scripts/gen_glb_manifest.py`
* `scripts/generate_reference_glbs.py`
* `scripts/glb_validate.py`
* `scripts/update_glb_metadata.py`
* `tests/perf/k6-quote-cnc.js`

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: coderabbitai[bot]

backend/tests/test_error_envelopes.py

@@ -9,6 +9,15 @@
 
 
 def _is_error_shape(payload: dict) -> bool:
+    """
+    Check whether a payload matches the error envelope shape: 'ok' equals False and 'error' is a dict containing 'code' and 'message'.
+    
+    Parameters:
+        payload (dict): The response payload to validate.
+    
+    Returns:
+        bool: True if the payload has 'ok' set to False and an 'error' dict with both 'code' and 'message', False otherwise.
+    """
     if not isinstance(payload, dict):
         return False
     if payload.get('ok') is not False:
@@ -28,10 +37,15 @@ def test_quote_invalid_payload_envelope() -> None:
 
 
 def test_cnc_invalid_payload_envelope() -> None:
+    """
+    Verifies the /api/cnc/export endpoint returns a standardized error envelope for an invalid JSON request body.
+    
+    Sends a request with a non-JSON payload and asserts the HTTP status is 400 or 422 and the response body matches the expected error shape (an object with `ok: False` and an `error` containing `code` and `message`).
+    """
     response = client.post(
         '/api/cnc/export',
         data='not-json',
         headers={'Content-Type': 'application/json'},
     )
     assert response.status_code in (400, 422)
-    assert _is_error_shape(response.json())
+    assert _is_error_shape(response.json())

scripts/gen_glb_manifest.py

@@ -13,6 +13,18 @@
 
 
 def manifest_entry(path: Path) -> dict:
+    """
+    Builds a manifest entry for the GLB file at the given path.
+    
+    Parameters:
+        path (Path): Path to the GLB file.
+    
+    Returns:
+        dict: Dictionary with keys:
+            - "file": asset path as "/models/<filename>".
+            - "sha256": hexadecimal SHA-256 digest of the file contents.
+            - "bytes": file size in bytes.
+    """
     data = path.read_bytes()
     return {
         "file": "/models/" + path.name,
@@ -22,6 +34,14 @@ def manifest_entry(path: Path) -> dict:
 
 
 def main() -> int:
+    """
+    Generate and print a JSON manifest of GLB model assets found under MODELS_PATTERN.
+    
+    Discovers matching .glb files, builds manifest entries for each using `manifest_entry`, writes the manifest as pretty-printed JSON to standard output, and returns an exit code.
+    
+    Returns:
+        int: Exit code `0` on success.
+    """
     paths = sorted(MODELS_PATTERN.parent.glob(MODELS_PATTERN.name))
     entries = [manifest_entry(path) for path in paths]
     manifest = {"models": entries}
@@ -30,4 +50,4 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(main())

scripts/generate_reference_glbs.py

@@ -33,22 +33,63 @@
 
 
 def pack_f32(values: Iterable[float]) -> bytes:
+    """
+    Pack an iterable of numbers into a binary blob of little-endian 32-bit floats.
+    
+    Parameters:
+        values (Iterable[float]): Sequence of numeric values to encode; each value is converted to a 32-bit IEEE 754 float.
+    
+    Returns:
+        bytes: Concatenation of little-endian 32-bit float representations of the input values.
+    """
     return b"".join(struct.pack("<f", float(v)) for v in values)
 
 
 def pack_u16(values: Iterable[int]) -> bytes:
+    """
+    Pack an iterable of integers into a concatenated little-endian 16-bit unsigned integer byte sequence.
+    
+    Parameters:
+        values (Iterable[int]): Sequence of values to encode; each value will be converted to an integer and encoded as a 16-bit unsigned little-endian value.
+    
+    Returns:
+        bytes: Concatenated binary representation of the encoded values.
+    """
     return b"".join(struct.pack("<H", int(v)) for v in values)
 
 
 def pad4(data: bytes, pad: bytes = b" ") -> bytes:
+    """
+    Pad a byte string so its length is a multiple of 4 by appending a specified byte.
+    
+    Parameters:
+        data (bytes): The input byte string to be padded.
+        pad (bytes): The byte sequence to append to reach a 4-byte boundary (defaults to a single space).
+    
+    Returns:
+        bytes: The input data padded on the right so its length is divisible by 4.
+    """
     remainder = (-len(data)) % 4
     if remainder:
         data += pad * remainder
     return data
 
 
 def build_box(width: float, height: float, depth: float, subdivisions: int = 2) -> Tuple[List[float], List[float], List[int]]:
-    """Create a box mesh with per-face subdivisions so LOD simplification has room to operate."""
+    """
+    Generate a subdivided box mesh aligned with the model origin.
+    
+    Parameters:
+        width (float): Box extent along the X axis.
+        height (float): Box extent along the Y axis.
+        depth (float): Box extent along the Z axis.
+        subdivisions (int): Number of subdivisions per face edge; 0 yields one quad per face.
+    
+    Returns:
+        positions (List[float]): Flat list of vertex positions [x, y, z, ...].
+        texcoords (List[float]): Flat list of per-vertex UV coordinates [u, v, ...].
+        indices (List[int]): Triangle index list referencing vertices (triplets per triangle).
+    """
 
     w, h, d = float(width), float(height), float(depth)
     positions: List[float] = []
@@ -98,12 +139,34 @@ def build_box(width: float, height: float, depth: float, subdivisions: int = 2)
 def create_glb_document(
     code: str, width: int, height: int, depth: int
 ) -> Tuple[Dict, bytes]:
+    """
+    Builds a glTF 2.0 document dictionary and a single concatenated binary buffer for a minimal box mesh with embedded 4x4 PNG textures and module metadata.
+    
+    Returns:
+        tuple: A pair (document, binary_blob) where `document` is the glTF JSON-compatible dictionary describing asset, scenes, nodes, meshes, materials, textures, images, bufferViews, accessors, and a buffer entry; and `binary_blob` is the bytes object containing the concatenated, 4-byte-aligned binary data for vertex attributes, indices, and embedded image files.
+    """
     positions, texcoords, indices = build_box(width, height, depth)
     position_blob = pack_f32(positions)
     texcoord_blob = pack_f32(texcoords)
     index_blob = pack_u16(indices)
 
     def add_view(blob: bytes, *, target: int | None = None) -> Tuple[int, bytes]:
+        """
+        Add a binary buffer view to the accumulating GLB buffer and return its index and padded bytes.
+        
+        Parameters:
+            blob (bytes): Raw binary payload to append to the shared buffer.
+            target (int | None): Optional GLTF bufferView `target` (e.g. 34962 for ARRAY_BUFFER); if None, no target is set.
+        
+        Returns:
+            tuple:
+                index (int): Index of the newly created bufferView in `buffer_views`.
+                padded (bytes): The input `blob` padded to a 4-byte boundary that was appended to the shared buffer.
+        
+        Side effects:
+            Appends the padded bytes to the nonlocal `buffer_bytes`, appends a bufferView entry to `buffer_views`,
+            and advances the nonlocal `byte_offset`.
+        """
         nonlocal buffer_bytes, byte_offset
         view = {"buffer": 0, "byteOffset": byte_offset, "byteLength": len(blob)}
         if target is not None:
@@ -233,6 +296,14 @@ def add_view(blob: bytes, *, target: int | None = None) -> Tuple[int, bytes]:
 
 
 def write_glb(path: Path, document: Dict, binary_blob: bytes) -> None:
+    """
+    Write a glTF 2.0 binary (GLB) file to the given path using the provided glTF JSON document and binary blob.
+    
+    Parameters:
+        path (Path): Filesystem path where the GLB file will be written; parent directories will be created if missing.
+        document (Dict): glTF JSON document structure to be serialized into the GLB JSON chunk.
+        binary_blob (bytes): Binary buffer data to be written into the GLB BIN chunk.
+    """
     json_bytes = pad4(json.dumps(document, separators=(",", ":")).encode("utf-8"))
     bin_bytes = pad4(binary_blob, b"\x00")
 
@@ -251,6 +322,11 @@ def write_glb(path: Path, document: Dict, binary_blob: bytes) -> None:
 
 
 def main() -> None:
+    """
+    Generate three deterministic reference GLB files and write them to the frontend public models directory.
+    
+    Creates the target models directory if missing, removes a legacy BaseCabinet600.glb if present, and produces three GLB assets with fixed codes and dimensions — "base_600" (600×720×580), "wall_900" (900×720×360), and "tall_600" (600×2100×580) — by calling create_glb_document for each and writing the resulting files with write_glb. Prints the relative output path for each written file.
+    """
     MODELS_DIR.mkdir(parents=True, exist_ok=True)
     legacy = MODELS_DIR / "BaseCabinet600.glb"
     if legacy.exists():
@@ -269,4 +345,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()

scripts/glb_validate.py

@@ -26,11 +26,29 @@ class Issue:
     message: str
 
     def __str__(self) -> str:
+        """
+        Return a compact, human-readable representation of the issue including a severity icon, code, and message.
+        
+        Returns:
+            str: Formatted string "<icon> [<code>] <message>" where the icon is "❌" for severity "ERROR" and "⚠️" for any other severity.
+        """
         icon = "❌" if self.severity == "ERROR" else "⚠️"
         return f"{icon} [{self.code}] {self.message}"
 
 
 def load_glb(path: Path) -> Dict:
+    """
+    Load a GLB file and return its parsed JSON content.
+    
+    Parameters:
+        path (Path): Filesystem path to a .glb file.
+    
+    Returns:
+        dict: The parsed JSON chunk contained in the GLB file.
+    
+    Raises:
+        ValueError: If the file is not a valid GLB (missing GLB header) or if the JSON chunk is absent.
+    """
     data = path.read_bytes()
     if data[:4] != b"glTF":
         raise ValueError("not a GLB file")
@@ -50,6 +68,15 @@ def load_glb(path: Path) -> Dict:
 
 
 def gather_root_nodes(doc: Dict) -> List[int]:
+    """
+    Retrieve the node indices for the active scene's root nodes.
+    
+    Parameters:
+        doc (Dict): Parsed glTF JSON document.
+    
+    Returns:
+        root_nodes (List[int]): List of node indices for the active scene. Returns an empty list if the document has no scenes.
+    """
     scenes = doc.get("scenes") or []
     scene_idx = doc.get("scene", 0)
     if not scenes:
@@ -58,6 +85,12 @@ def gather_root_nodes(doc: Dict) -> List[int]:
 
 
 def compute_bounds(doc: Dict) -> Optional[Tuple[List[float], List[float]]]:
+    """
+    Compute the axis-aligned bounding box across all mesh primitives that provide POSITION accessor min/max.
+    
+    Returns:
+        A tuple `(min_vals, max_vals)` where each is a 3-element list `[x, y, z]` representing the aggregated minimum and maximum coordinates, or `None` if no POSITION accessors with valid `min`/`max` were found.
+    """
     accessors = doc.get("accessors") or []
     meshes = doc.get("meshes") or []
     min_vals = [math.inf, math.inf, math.inf]
@@ -81,6 +114,14 @@ def compute_bounds(doc: Dict) -> Optional[Tuple[List[float], List[float]]]:
 
 
 def triangle_count(doc: Dict) -> int:
+    """
+    Compute the total number of triangles across all meshes in a glTF JSON document.
+    
+    For each mesh primitive, uses the indices accessor count divided by three when present; otherwise uses the POSITION accessor count divided by three. Missing accessors or missing counts are treated as zero contribution.
+    
+    Returns:
+        int: Total triangle count summed across all mesh primitives.
+    """
     total = 0
     accessors = doc.get("accessors") or []
     for mesh in doc.get("meshes") or []:
@@ -98,6 +139,22 @@ def triangle_count(doc: Dict) -> int:
 
 
 def validate(path: Path, fail_on_warning: bool, warn_threshold: int) -> Tuple[int, int, List[Issue]]:
+    """
+    Validate a Paform GLB asset and collect detected issues.
+    
+    Performs schema, metadata, material, mesh, bounds, panel type, and LOD validations and aggregates detected issues.
+    
+    Parameters:
+        path (Path): Filesystem path to the GLB file to validate.
+        fail_on_warning (bool): If True and there are warnings but no errors, treat the run as an error (affects returned counts and issue list).
+        warn_threshold (int): If not None and the number of warnings exceeds this threshold, a WARN_THRESHOLD error will be added.
+    
+    Returns:
+        Tuple[int, int, List[Issue]]: A tuple of (num_errors, num_warnings, issues) where:
+            - num_errors is the number of issues with severity "ERROR" after applying warn_threshold and fail_on_warning rules.
+            - num_warnings is the number of issues with severity "WARN" originally detected.
+            - issues is the list of Issue objects in the order they were detected, with any additional ERROR issues appended for warn-threshold or fail-on-warning promotion.
+    """
     issues: List[Issue] = []
     try:
         doc = load_glb(path)
@@ -234,6 +291,15 @@ def validate(path: Path, fail_on_warning: bool, warn_threshold: int) -> Tuple[in
 
 
 def main(argv: Sequence[str] | None = None) -> int:
+    """
+    Run the command-line GLB validator for the given paths and return a process exit code.
+    
+    Parameters:
+        argv (Sequence[str] | None): Optional list of CLI arguments to parse; if None, reads from sys.argv.
+    
+    Returns:
+        int: Exit status code — 0 if all files passed, 1 if warnings were escalated to errors (no other errors), 2 if any validation errors were found.
+    """
     parser = argparse.ArgumentParser(description="Validate Paform GLB files")
     parser.add_argument("paths", nargs="+", help="paths or globs to GLB files")
     parser.add_argument("--warn-threshold", type=int, default=5, help="maximum allowed warnings before failure")
@@ -261,4 +327,4 @@ def main(argv: Sequence[str] | None = None) -> int:
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())