cfengine dev lint-docs: Improved logging and error messages

Signed-off-by: Ole Herman Schumacher Elgesem <[email protected]>

Author: olehermanse

src/cfengine_cli/docs.py

@@ -109,8 +109,16 @@ def fn_extract(origin_path, snippet_path, _language, first_line, last_line):
         raise UserError(f"Couldn't open '{origin_path}' or '{snippet_path}'")
 
 
+def lint_json_file(snippet_abs_path, origin_path, snippet_number, first_line, prefix=None):
+    with open(snippet_abs_path, "r") as f:
+        json.loads(f.read())
+    if prefix:
+        print(prefix, end="")
+    print(f"PASS: Snippet {snippet_number} at '{origin_path}:{first_line}' (json)")
+    return 0
+
 def fn_check_syntax(
-    origin_path, snippet_path, language, first_line, _last_line, snippet_number
+    origin_path, snippet_path, language, first_line, _last_line, snippet_number, prefix=None
 ):
     snippet_abs_path = os.path.abspath(snippet_path)
 
@@ -122,14 +130,13 @@ def fn_check_syntax(
     match language:
         case "cf":
             r = lint_policy_file(
-                snippet_abs_path, origin_path, first_line + 1, snippet_number
+                snippet_abs_path, origin_path, first_line + 1, snippet_number, prefix
             )
             if r != 0:
                 raise UserError(f"Error when checking '{origin_path}'")
         case "json":
             try:
-                with open(snippet_abs_path, "r") as f:
-                    json.loads(f.read())
+                lint_json_file(snippet_abs_path, origin_path, snippet_number, first_line, prefix)
             except json.decoder.JSONDecodeError as e:
                 raise UserError(f"Error when checking '{snippet_abs_path}': {str(e)}")
             except Exception as e:
@@ -220,7 +227,12 @@ def _process_markdown_code_blocks(
 
     parsed_markdowns = get_markdown_files(path, languages)
 
-    for origin_path in parsed_markdowns["files"].keys():
+    origin_paths = sorted(parsed_markdowns["files"].keys())
+    origin_paths_len = len(origin_paths)
+
+    for origin_paths_i, origin_path in enumerate(origin_paths):
+        percentage = int(100 * (origin_paths_i + 1)/origin_paths_len)
+        prefix = f"[{origin_paths_i + 1}/{origin_paths_len} ({percentage}%)] "
         offset = 0
         for i, code_block in enumerate(
             parsed_markdowns["files"][origin_path]["code-blocks"]
@@ -257,6 +269,7 @@ def _process_markdown_code_blocks(
                         code_block["first_line"],
                         code_block["last_line"],
                         snippet_number,
+                        prefix
                     )
                 except Exception as e:
                     if cleanup:

src/cfengine_cli/lint.py

@@ -98,7 +98,7 @@ def _walk(filename, lines, node) -> int:
 
 
 def lint_policy_file(
-    filename, original_filename=None, original_line=None, snippet=None
+    filename, original_filename=None, original_line=None, snippet=None, prefix=None
 ):
     assert original_filename is None or type(original_filename) is str
     assert original_line is None or type(original_line) is int
@@ -123,7 +123,14 @@ def lint_policy_file(
 
     root_node = tree.root_node
     if root_node.type != "source_file":
-        print(f"Error: Failed to parse snippet ('{filename}') - Is this valid CFEngine policy?")
+        if snippet:
+            assert original_filename and original_line
+            print(
+                f"Error: Failed to parse policy snippet {snippet} at '{original_filename}:{original_line}'"
+            )
+        else:
+            print(f"       Empty policy file '{filename}'")
+        print("       Is this valid CFEngine policy?")
         print("")
         lines = original_data.decode().split("\n")
         if not len(lines) <= 5:
@@ -144,17 +151,19 @@ def lint_policy_file(
             print(f"Error: Empty policy file '{filename}'")
         errors += 1
     errors += _walk(filename, lines, root_node)
+    if prefix:
+        print(prefix, end="")
     if errors == 0:
         if snippet:
             assert original_filename and original_line
-            print(f"PASS: Snippet {snippet} at '{original_filename}:{original_line}'")
+            print(f"PASS: Snippet {snippet} at '{original_filename}:{original_line}' (cf3)")
         else:
             print(f"PASS: {filename}")
         return 0
 
     if snippet:
         assert original_filename and original_line
-        print(f"FAIL: Snippet {snippet} at '{original_filename}:{original_line}'")
+        print(f"FAIL: Snippet {snippet} at '{original_filename}:{original_line}' (cf3)")
     else:
         print(f"FAIL: {filename} ({errors} error{'s' if errors > 0 else ''})")
     return errors