format.py: Added unit tests and docstrings

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Ole Herman Schumacher Elgesem <ole.elgesem@northern.tech>

Author: olehermanse

src/cfengine_cli/format.py

@@ -50,6 +50,17 @@ def update_previous(self, node):
 
 
 def stringify_children_from_strings(parts):
+    """Join pre-extracted string tokens into a formatted parameter list.
+
+    Used when formatting bundle/body headers. Comments are
+    stripped from the parameter_list node before this function is called,
+    so `parts` contains only the structural tokens: "(", identifiers, ","
+    separators, and ")".  The function removes any trailing comma before
+    ")", then joins the tokens with appropriate spacing (space after each
+    comma, no space after "(" or before ")").
+
+    Example: ["(", "a", ",", "b", ",", ")"] -> "(a, b)"
+    """
     # Remove trailing comma before closing paren
     cleaned = []
     for i, part in enumerate(parts):
@@ -69,6 +80,19 @@ def stringify_children_from_strings(parts):
 
 
 def stringify_children(children):
+    """Join a list of tree-sitter nodes into a single-line string.
+
+    Operates on the direct child nodes of a CFEngine syntax construct
+    (e.g. a list, call, or attribute). Each child is recursively
+    flattened via stringify_single_line(). Spacing rules:
+      - A space is inserted after each "," separator.
+      - A space is inserted before and after "=>" (fat arrow).
+      - No extra space otherwise (e.g. no space after "(" or before ")").
+
+    Used by stringify_single_line() to recursively flatten any node with
+    children, and by maybe_split_generic_list() to attempt a single-line
+    rendering before falling back to multi-line splitting.
+    """
     result = ""
     previous = None
     for child in children:

tests/unit/test_format.py

@@ -0,0 +1,70 @@
+from cfengine_cli.format import stringify_children_from_strings, stringify_children
+
+
+class MockNode:
+    """Minimal stand-in for a tree-sitter Node used by stringify_children."""
+
+    def __init__(self, node_type, node_text=None, children=None):
+        self.type = node_type
+        self.text = node_text.encode("utf-8") if node_text is not None else None
+        self.children = children or []
+
+def _leaf(node_type, node_text=None):
+    return MockNode(node_type, node_text or node_type)
+
+def test_stringify_children_from_strings():
+    assert stringify_children_from_strings([]) == ""
+    assert stringify_children_from_strings(["foo"]) == "foo"
+    assert stringify_children_from_strings(["(", "a", ")"]) == "(a)"
+    assert stringify_children_from_strings(["(", "a", ",", "b", ")"]) == "(a, b)"
+    assert stringify_children_from_strings(["(", "a", ",", ")"]) == "(a)"
+    assert (
+        stringify_children_from_strings(["(", "a", ",", "b", ",", ")"])
+        == "(a, b)"
+    )
+    assert stringify_children_from_strings(["a", "b", "c"]) == "a b c"
+    assert stringify_children_from_strings(["a", ",", "b"]) == "a, b"
+    assert stringify_children_from_strings(["(", ")"]) == "()"
+    parts = ["(", "x", ",", "y", ",", "z", ")"]
+    assert stringify_children_from_strings(parts) == "(x, y, z)"
+
+def test_stringify_children():
+    assert stringify_children([]) == ""
+    assert stringify_children([_leaf("identifier", "foo")]) == "foo"
+
+    nodes = [_leaf("string", '"a"'), _leaf(","), _leaf("string", '"b"')]
+    assert stringify_children(nodes) == '"a", "b"'
+
+    nodes = [_leaf("identifier", "lval"), _leaf("=>"), _leaf("string", '"rval"')]
+    assert stringify_children(nodes) == 'lval => "rval"'
+
+    nodes = [_leaf("("), _leaf("identifier", "x"), _leaf(")")]
+    assert stringify_children(nodes) == "(x)"
+
+    nodes = [
+        _leaf("{"),
+        _leaf("string", '"a"'),
+        _leaf(","),
+        _leaf("string", '"b"'),
+        _leaf("}"),
+    ]
+    assert stringify_children(nodes) == '{"a", "b"}'
+    nodes = [
+        _leaf("identifier", "package_name"),
+        _leaf("=>"),
+        _leaf("string", '"nginx"'),
+    ]
+
+    assert stringify_children(nodes) == 'package_name => "nginx"'
+    inner = MockNode(
+        "call",
+        children=[
+            _leaf("calling_identifier", "func"),
+            _leaf("("),
+            _leaf("string", '"arg"'),
+            _leaf(")"),
+        ],
+    )
+
+    nodes = [_leaf("identifier", "x"), _leaf("=>"), inner]
+    assert stringify_children(nodes) == 'x => func("arg")'