better consideration for windows-based runners (#53)

* better consideration for windows-based runners

- allow a path to clang-tools be passed to version (on windows platform)
- annotate w/ filename using posix path delimiters when env is a CI runner
- add some type hinting

* ignore invalid version input on non-windows env

* add windows runner example to README

* append /bin automatically

* update README about the last commit

* update `cpp-linter -h` output

* add more shorthand CLI args

* Update cpp_linter/run.py

Co-authored-by: Peter Shen <xianpeng.shen@gmail.com>

Co-authored-by: Peter Shen <xianpeng.shen@gmail.com>

Author: 2bndy5

README.md

@@ -128,6 +128,57 @@ jobs:
 
 This action creates 1 output variable named `checks-failed`. Even if the linting checks fail for source files this action will still pass, but users' CI workflows can use this action's output to exit the workflow early if that is desired.
 
+## Using a Windows-based runner
+
+This action can only be run on a runner using the Ubuntu Operating System. However, this action's source code (essentially a python package) can be used on a runner using the Windows Operating System.
+
+Note: MacOS-based runners have not been tested, but the same approach applies.
+
+This example makes use of another action
+([KyleMayes/install-llvm-action](https://github.com/KyleMayes/install-llvm-action))
+to install a certain version of clang-tidy and clang-format.
+
+```yml
+on:
+  push:
+    paths-ignore: "docs/**"
+  pull_request:
+    paths-ignore: "docs/**"
+
+jobs:
+  cpp-linter:
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+
+      - name: Install clang-tools
+        uses: KyleMayes/install-llvm-action@v1
+        with:
+          # v12 is the recommended minimum for the Visual Studio compiler
+          version: 12
+          # specifying an install path is required because
+          # Windows runners already have a certain version of LLVM installed
+          directory: ${{ runner.temp }}/llvm
+
+      - name: Install linter python package
+        run: python3 -m pip install git+https://github.com/shenxianpeng/cpp-linter-action
+
+      - name: run linter as a python package
+        id: linter
+        # pass the installed path to the '--version' argument
+        run: cpp-linter --version=${{ runner.temp }}/llvm
+
+      - name: Fail fast?!
+        if: steps.linter.outputs.checks-failed > 0
+        run: echo "Some files failed the linting checks!"
+        # for actual deployment
+        # run: exit 1
+```
+
+All input options listed above are specified by pre-pending a `--`. You can also install this repo locally and run `cpp-linter -h` for more detail.
+
 ## Example
 
 <!--intro-end-->

cpp_linter/__init__.py

@@ -25,6 +25,7 @@
     logger.debug("rich module not found")
 
 # global constant variables
+IS_ON_RUNNER = bool(os.getenv("CI"))
 GITHUB_SHA = os.getenv("GITHUB_SHA", "")
 GITHUB_TOKEN = os.getenv("GITHUB_TOKEN", os.getenv("GIT_REST_API", ""))
 API_HEADERS = {"Accept": "application/vnd.github.v3.text+json",}

cpp_linter/clang_tidy.py

@@ -1,7 +1,7 @@
 """Parse output from clang-tidy's stdout"""
 import os
 import re
-from . import GlobalParser  # , logger
+from . import GlobalParser, IS_ON_RUNNER  # , logger
 
 NOTE_HEADER = re.compile("^(.*):(\d+):(\d+):\s(\w+):(.*)\[(.*)\]$")
 
@@ -37,11 +37,11 @@ def __init__(self, notification_line: tuple):
             self.diagnostic,
         ) = notification_line
 
-        self.note_info = self.note_info.strip()
-        self.note_type = self.note_type.strip()
+        self.note_info: str = self.note_info.strip()
+        self.note_type: str = self.note_type.strip()
         self.line = int(self.line)
         self.cols = int(self.cols)
-        self.filename = self.filename.replace(os.getcwd() + os.sep, "")
+        self.filename: str = self.filename.replace(os.getcwd() + os.sep, "")
         self.fixit_lines = []
 
     def __repr__(self) -> str:
@@ -70,15 +70,19 @@ def log_command(self) -> str:
             - [A notice message](https://docs.github.com/en/actions/learn-github-
               actions/workflow-commands-for-github-actions#setting-a-notice-message)
         """
-        return "::{} file={},line={},title={}:{}:{} [{}]::{}".format(
-            "notice" if self.note_type.startswith("note") else self.note_type,
-            self.filename,
-            self.line,
-            self.filename,
-            self.line,
-            self.cols,
-            self.diagnostic,
-            self.note_info,
+        filename = self.filename
+        if IS_ON_RUNNER:
+            filename = self.filename.replace(os.sep, "/")
+        return (
+            "::{} file={file},line={line},title={file}:{line}:{cols} [{diag}]::"
+            "{info}".format(
+                "notice" if self.note_type.startswith("note") else self.note_type,
+                file=filename,
+                line=self.line,
+                cols=self.cols,
+                diag=self.diagnostic,
+                info=self.note_info,
+            )
         )
 
 

cpp_linter/run.py

@@ -84,7 +84,8 @@
     "--version",
     default="10",
     help="The desired version of the clang tools to use. Accepted options are strings "
-    "which can be 6.0, 7, 8, 9, 10, 11, 12. Defaults to %(default)s.",
+    "which can be 8, 9, 10, 11, 12, 13, 14. Defaults to %(default)s. On Windows, this "
+    "can also be a path to the install location of LLVM",
 )
 cli_arg_parser.add_argument(
     "-e",
@@ -107,23 +108,26 @@
     help="Set this option with paths to ignore. In the case of multiple "
     "paths, you can set this option (multiple times) for each path. This can "
     "also have files, but the file's relative path has to be specified as well "
-    "with the filename.",
+    "with the filename. Prefix a path with '!' to explicitly not ignore it.",
 )
 cli_arg_parser.add_argument(
+    "-l",
     "--lines-changed-only",
     default="false",
     type=lambda input: input.lower() == "true",
     help="Set this option to 'true' to only analyse changes in the event's diff. "
     "Defaults to %(default)s.",
 )
 cli_arg_parser.add_argument(
+    "-f",
     "--files-changed-only",
     default="false",
     type=lambda input: input.lower() == "true",
     help="Set this option to 'false' to analyse any source files in the repo. "
     "Defaults to %(default)s.",
 )
 cli_arg_parser.add_argument(
+    "-t",
     "--thread-comments",
     default="false",
     type=lambda input: input.lower() == "true",
@@ -394,6 +398,11 @@ def run_clang_tidy(
     cmds = [f"clang-tidy-{version}"]
     if sys.platform.startswith("win32"):
         cmds = ["clang-tidy"]
+        if os.path.exists(version + os.sep + "bin"):
+            cmds = [f"{version}\\bin\\clang-tidy.exe"]
+    elif not version.isdigit():
+        logger.warning("ignoring invalid version number %s.", version)
+        cmds = ["clang-tidy"]
     if checks:
         cmds.append(f"-checks={checks}")
     cmds.append("--export-fixes=clang_tidy_output.yml")
@@ -440,11 +449,17 @@ def run_clang_format(
         lines_changed_only: A flag that forces focus on only changes in the event's
             diff info.
     """
+    is_on_windows = sys.platform.startswith("win32")
     cmds = [
-        "clang-format" + ("" if sys.platform.startswith("win32") else f"-{version}"),
+        "clang-format" + ("" if is_on_windows else f"-{version}"),
         f"-style={style}",
         "--output-replacements-xml",
     ]
+    if is_on_windows and os.path.exists(version + os.sep + "bin"):
+        cmds[0] = f"{version}\\bin\\clang-format.exe"
+    elif not is_on_windows and not version.isdigit():
+        logger.warning("ignoring invalid version number %s.", version)
+        cmds[0] = "clang-format"
     if lines_changed_only:
         for line_range in file_obj["line_filter"]["lines"]:
             cmds.append(f"--lines={line_range[0]}:{line_range[1]}")