tests: kdoc: re-implement in python

The existing kdoc test is written in shell, based on a simple heuristic of
checking whether the number of lines of output from scripts/kernel-doc
increases.

This test can pass in some cases even when new warnings are introduced,
such as if a single patch adds some new warnings while removing others. In
addition, the provided log output is not very useful to humans. It uses a
traditional diff to compare the prior and current warnings. Because the
warnings include line number data, this results in an unreadable mess.

Implementing a proper comparison in the shell script is possible, but the
resulting logic and code is difficult to maintain. Ultimately, what we want
to do is a sort of set intersection on the warnings while ignoring line
numbers. Implementing this in python is much more practical.

As a first step, convert the kdoc test into a python module. Commands are
executed via subprocess. The improved comparison algorithm will be
implemented in a following change.

Since we will be implementing a new comparison algorithm, do not bother
porting the "diff" implementation forward. This results in a temporary
regression as we no longer compute the difference or file summary for the
user. This will be resolved with the following change implementing the
improved algorithm.

This version has a couple of minor changes worth nothing:

1) The log output is now in stdout instead of stderr, since the
   python-based tests do not support logging output to the stderr file.
2) We no longer print out "Checking the tree..." lines.
3) The description line is included within the stdout log text as well as
   the desc file.

Signed-off-by: Jacob Keller <[email protected]>

Author: jacob-keller

tests/patch/kdoc/info.json

@@ -1,4 +1,5 @@
 {
-  "run": ["kdoc.sh"],
+  "pymod": "test",
+  "pyfunc": "kdoc",
   "pull-requests": true
 }

tests/patch/kdoc/kdoc.sh

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: GPL-2.0
+
+""" Test if kernel-doc generates new warnings """
+
+import os
+import subprocess
+from typing import List, Optional, Tuple
+
+def get_git_head(tree) -> str:
+    """ Get the git commit ID for head commit. """
+
+    cmd = ["git", "rev-parse", "HEAD"]
+    result = subprocess.run(cmd, cwd=tree.path, capture_output=True, text=True,
+                            check=True)
+
+    return result.stdout.strip()
+
+def run_kernel_doc(tree, commitish, files):
+    """ Run ./scripts/kdoc on a given commit and capture its results. """
+
+    cmd = ["git", "checkout", "-q", commitish]
+    subprocess.run(cmd, cwd=tree.path, capture_output=False, check=True)
+
+    cmd = ["./scripts/kernel-doc", "-Wall", "-none"] + files
+    result = subprocess.run(cmd, cwd=tree.path, text=True, check=False,
+                            stderr=subprocess.PIPE)
+
+    return result.stderr.strip().split('\n')
+
+def extract_files(patch):
+    """Extract paths added or modified by the patch."""
+
+    all_files = set()
+    mod_files = set()
+    lines = patch.raw_patch.split("\n")
+
+    # Walk lines, skip last since it doesn't have next
+    for i, line in enumerate(lines[:-1]):
+        next_line = lines[i + 1]
+
+        if not next_line.startswith("+++ b/"):
+            continue
+
+        file_path = next_line[6:]
+
+        all_files.add(file_path)
+
+        if line != "--- /dev/null":
+            mod_files.add(file_path)
+
+    return list(mod_files), list(all_files)
+
+def kdoc(tree, patch, result_dir) -> Tuple[int, str, str]:
+    """ Main function / entry point """
+
+    mod_files, all_files = extract_files(patch)
+
+    if not mod_files or not all_files:
+        return 1, "Patch has no modified files?", ""
+
+    ret = 0
+    desc = ""
+    log = []
+
+    head_commit = get_git_head(tree)
+
+    try:
+        incumbent_warnings = run_kernel_doc(tree, "HEAD~", mod_files)
+        log += ["Warnings before patch:"]
+        log.extend(map(str, incumbent_warnings))
+
+        current_warnings = run_kernel_doc(tree, head_commit, all_files)
+        log += ["", "Current warnings:"]
+        log.extend(map(str, current_warnings))
+    except subprocess.CalledProcessError as e:
+        desc = f'{e.cmd} failed with exit code {e.returncode}'
+        if e.stderr:
+            log += e.stderr.split('\n')
+        ret = 1
+
+        return ret, desc, "\n".join(log)
+
+    incumbent_count = len(incumbent_warnings)
+    current_count = len(current_warnings)
+
+    desc = f'Errors and warnings before: {incumbent_count} This patch: {current_count}'
+    log += ["", desc]
+
+    if current_count > incumbent_count:
+        ret = 1
+
+    return ret, desc, "\n".join(log)