TheRock/compiler/amd-llvm/clang-tools-extra/test/clang-tidy/check_clang_tidy.py

#!/usr/bin/env python3
#
# ===-----------------------------------------------------------------------===#
#
# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
# See https://llvm.org/LICENSE.txt for license information.
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
#
# ===------------------------------------------------------------------------===#

"""
ClangTidy Test Helper
=====================

This script is used to simplify writing, running, and debugging tests compatible
with llvm-lit. By default it runs clang-tidy in fix mode and uses FileCheck to
verify messages and/or fixes.

For debugging, with --export-fixes, the tool simply exports fixes to a provided
file and does not run FileCheck.

Extra arguments, those after the first -- if any, are passed to either
clang-tidy or clang:
* Arguments between the first -- and second -- are clang-tidy arguments.
  * May be only whitespace if there are no clang-tidy arguments.
  * clang-tidy's --config would go here.
* Arguments after the second -- are clang arguments

Examples
--------

  // RUN: %check_clang_tidy %s llvm-include-order %t -- -- -isystem %S/Inputs

or

  // RUN: %check_clang_tidy %s llvm-include-order --export-fixes=fixes.yaml %t -std=c++20

Notes
-----
  -std=c++(98|11|14|17|20)-or-later:
    This flag will cause multiple runs within the same check_clang_tidy
    execution. Make sure you don't have shared state across these runs.
"""

import argparse
import os
import pathlib
import platform
import re
import subprocess
import sys
from collections import defaultdict
from typing import Dict, List, Sequence, Tuple


def write_file(file_name: str, text: str) -> None:
    with open(file_name, "w", encoding="utf-8") as f:
        f.write(text)
        f.truncate()


def try_run(args: List[str], raise_error: bool = True) -> str:
    try:
        process_output = subprocess.check_output(args, stderr=subprocess.STDOUT).decode(
            errors="ignore"
        )
    except subprocess.CalledProcessError as e:
        process_output = e.output.decode(errors="ignore")
        print("%s failed:\n%s" % (" ".join(args), process_output))
        if raise_error:
            raise
    return process_output


# This class represents the appearance of a message prefix in a file.
class MessagePrefix:
    def __init__(self, label: str) -> None:
        self.has_message = False
        self.prefixes: List[str] = []
        self.label = label

    def check(self, file_check_suffix: str, input_text: str) -> bool:
        self.prefix = self.label + file_check_suffix
        self.has_message = self.prefix in input_text
        if self.has_message:
            self.prefixes.append(self.prefix)
        return self.has_message


class CheckRunner:
    def __init__(self, args: argparse.Namespace, extra_args: List[str]) -> None:
        self.resource_dir = args.resource_dir
        self.assume_file_name = args.assume_filename
        self.input_file_name = args.input_file_name
        self.check_name = args.check_name
        self.temp_file_name = args.temp_file_name
        self.check_headers = args.check_headers
        self.original_file_name = f"{self.temp_file_name}.orig"
        self.expect_clang_tidy_error = args.expect_clang_tidy_error
        self.std = args.std
        self.check_suffix = args.check_suffix
        self.input_text = ""
        self.has_check_fixes = False
        self.has_check_messages = False
        self.has_check_notes = False
        self.expect_no_diagnosis = False
        self.export_fixes = args.export_fixes
        self.fixes = MessagePrefix("CHECK-FIXES")
        self.messages = MessagePrefix("CHECK-MESSAGES")
        self.notes = MessagePrefix("CHECK-NOTES")
        self.match_partial_fixes = args.match_partial_fixes

        file_name_with_extension = self.assume_file_name or self.input_file_name
        _, extension = os.path.splitext(file_name_with_extension)
        if extension not in [".c", ".hpp", ".m", ".mm", ".cu"]:
            extension = ".cpp"
        self.temp_file_name = self.temp_file_name + extension

        self.clang_extra_args = []
        self.clang_tidy_extra_args = extra_args
        if "--" in extra_args:
            i = self.clang_tidy_extra_args.index("--")
            self.clang_extra_args = self.clang_tidy_extra_args[i + 1 :]
            self.clang_tidy_extra_args = self.clang_tidy_extra_args[:i]

        self.check_header_map: Dict[str, str] = {}
        self.header_dir = f"{self.temp_file_name}.headers"
        if self.check_headers:
            self.check_header_map = {
                os.path.normcase(
                    os.path.abspath(os.path.join(self.header_dir, os.path.basename(h)))
                ): os.path.abspath(h)
                for h in self.check_headers
            }

            self.clang_extra_args.insert(0, f"-I{self.header_dir}")

        # If the test does not specify a config style, force an empty one; otherwise
        # auto-detection logic can discover a ".clang-tidy" file that is not related to
        # the test.
        if not any(
            [re.match("^-?-config(-file)?=", arg) for arg in self.clang_tidy_extra_args]
        ):
            self.clang_tidy_extra_args.append("--config={}")

        if extension in [".m", ".mm"]:
            self.clang_extra_args = [
                "-fobjc-abi-version=2",
                "-fobjc-arc",
                "-fblocks",
            ] + self.clang_extra_args

        self.clang_extra_args.append(f"-std={self.std}")

        # Tests should not rely on STL being available, and instead provide mock
        # implementations of relevant APIs.
        self.clang_extra_args.append("-nostdinc++")

        # Include stub std headers directory as a system include
        # path so individual tests don't need to specify it.
        headers_dir = os.path.join(
            os.path.dirname(__file__), "checkers", "Inputs", "Headers", "std"
        )
        if os.path.isdir(headers_dir):
            self.clang_extra_args.extend(["-isystem", headers_dir])

        if self.resource_dir is not None:
            self.clang_extra_args.append("-resource-dir=%s" % self.resource_dir)

    def read_input(self) -> None:
        # Use a "\\?\" prefix on Windows to handle long file paths transparently:
        # https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation
        file_name = self.input_file_name
        if platform.system() == "Windows":
            file_name = "\\\\?\\" + os.path.abspath(file_name)
        with open(file_name, "r", encoding="utf-8") as input_file:
            self.input_text = input_file.read()

    def get_prefixes(self) -> None:
        for suffix in self.check_suffix:
            if suffix and not re.match("^[A-Z0-9\\-]+$", suffix):
                sys.exit(
                    'Only A..Z, 0..9 and "-" are allowed in check suffixes list, '
                    f'but "{suffix}" was given'
                )

            file_check_suffix = ("-" + suffix) if suffix else ""

            has_check_fix = self.fixes.check(file_check_suffix, self.input_text)
            self.has_check_fixes = self.has_check_fixes or has_check_fix

            has_check_message = self.messages.check(file_check_suffix, self.input_text)
            self.has_check_messages = self.has_check_messages or has_check_message

            has_check_note = self.notes.check(file_check_suffix, self.input_text)
            self.has_check_notes = self.has_check_notes or has_check_note

            if has_check_note and has_check_message:
                sys.exit(
                    "Please use either %s or %s but not both"
                    % (self.notes.prefix, self.messages.prefix)
                )

            if not has_check_fix and not has_check_message and not has_check_note:
                self.expect_no_diagnosis = True

        expect_diagnosis = (
            self.has_check_fixes or self.has_check_messages or self.has_check_notes
        )
        if self.expect_no_diagnosis and expect_diagnosis:
            sys.exit(
                "%s, %s or %s not found in the input"
                % (
                    self.fixes.prefix,
                    self.messages.prefix,
                    self.notes.prefix,
                )
            )
        assert expect_diagnosis or self.expect_no_diagnosis

    def _remove_filecheck_content(self, text: str) -> str:
        # Remove the contents of the CHECK lines to avoid CHECKs matching on
        # themselves. We need to keep the comments to preserve line numbers while
        # avoiding empty lines which could potentially trigger formatting-related
        # checks.
        return re.sub("// *CHECK-[A-Z0-9\\-]*:[^\r\n]*", "//", text)

    def _filter_prefixes(self, prefixes: Sequence[str], check_file: str) -> List[str]:
        """
        Filter prefixes to only those present in the check file.

        - Input:
            prefixes: A list of potential FileCheck prefixes.
            check_file: The file to check for prefix presence.
        - Output:
            A list of prefixes found in the check file.

        FileCheck fails if a specified prefix is not present. This is common
        in header testing scenarios where expectations differ between the
        main file and the header (e.g. the main file might verify code
        changes while the header only verifies warnings).
        """
        if check_file == self.input_file_name:
            content = self.input_text
        else:
            with open(check_file, "r", encoding="utf-8") as f:
                content = f.read()
        return [p for p in prefixes if p in content]

    def prepare_test_inputs(self) -> None:
        cleaned_test = self._remove_filecheck_content(self.input_text)
        write_file(self.temp_file_name, cleaned_test)
        write_file(self.original_file_name, cleaned_test)

        if self.check_headers:
            os.makedirs(self.header_dir, exist_ok=True)

            for temp_header_path, header in self.check_header_map.items():
                with open(header, "r", encoding="utf-8") as f:
                    cleaned_header = self._remove_filecheck_content(f.read())

                write_file(temp_header_path, cleaned_header)
                write_file(f"{temp_header_path}.orig", cleaned_header)

    def run_clang_tidy(self) -> str:
        args = (
            [
                "clang-tidy",
                "--experimental-custom-checks",
                self.temp_file_name,
            ]
            + [
                (
                    "-fix"
                    if self.export_fixes is None
                    else f"--export-fixes={self.export_fixes}"
                )
            ]
            + [
                f"--checks=-*,{self.check_name}",
            ]
            + self.clang_tidy_extra_args
            + ["--"]
            + self.clang_extra_args
        )
        if self.expect_clang_tidy_error:
            args.insert(0, "not")
        print(f"Running {repr(args)}...")
        clang_tidy_output = try_run(args)
        print("------------------------ clang-tidy output -----------------------")
        print(
            clang_tidy_output.encode(sys.stdout.encoding, errors="replace").decode(
                sys.stdout.encoding
            )
        )
        print("------------------------------------------------------------------")

        diff_output = try_run(
            ["diff", "-u", self.original_file_name, self.temp_file_name], False
        )
        if self.check_headers:
            for temp_header_path in self.check_header_map:
                diff_output += try_run(
                    ["diff", "-u", f"{temp_header_path}.orig", temp_header_path], False
                )

        print("------------------------------ Fixes -----------------------------")
        print(diff_output)
        print("------------------------------------------------------------------")
        return clang_tidy_output

    def check_no_diagnosis(self, clang_tidy_output: str) -> None:
        if clang_tidy_output != "":
            sys.exit("No diagnostics were expected, but found the ones above")

    def check_fixes(self, input_file: str = "", check_file: str = "") -> None:
        if not (check_file or self.has_check_fixes):
            return

        input_file = input_file or self.temp_file_name
        check_file = check_file or self.input_file_name
        active_prefixes = self._filter_prefixes(self.fixes.prefixes, check_file)

        if not active_prefixes:
            return

        try_run(
            [
                "FileCheck",
                f"--input-file={input_file}",
                check_file,
                f"--check-prefixes={','.join(active_prefixes)}",
                (
                    "--strict-whitespace"  # Keeping past behavior.
                    if self.match_partial_fixes
                    else "--match-full-lines"
                ),
            ]
        )

    def check_messages(
        self,
        clang_tidy_output: str,
        messages_file: str = "",
        check_file: str = "",
    ) -> None:
        if not check_file and not self.has_check_messages:
            return

        messages_file = messages_file or f"{self.temp_file_name}.msg"
        check_file = check_file or self.input_file_name

        active_prefixes = self._filter_prefixes(self.messages.prefixes, check_file)
        if not active_prefixes:
            return

        write_file(messages_file, clang_tidy_output)
        try_run(
            [
                "FileCheck",
                f"-input-file={messages_file}",
                check_file,
                f"-check-prefixes={','.join(active_prefixes)}",
                "-implicit-check-not={{warning|error}}:",
            ]
        )

    def check_notes(self, clang_tidy_output: str) -> None:
        if self.has_check_notes:
            notes_file = f"{self.temp_file_name}.notes"
            filtered_output = [
                line
                for line in clang_tidy_output.splitlines()
                if not ("note: FIX-IT applied" in line)
            ]
            write_file(notes_file, "\n".join(filtered_output))
            try_run(
                [
                    "FileCheck",
                    f"-input-file={notes_file}",
                    self.input_file_name,
                    f"-check-prefixes={','.join(self.notes.prefixes)}",
                    "-implicit-check-not={{note|warning|error}}:",
                ]
            )

    def _separate_messages(self, clang_tidy_output: str) -> Tuple[str, Dict[str, str]]:
        """
        Separates diagnostics for the main file and headers.

        - Input: The raw diagnostic output from clang-tidy.
        - Output: A tuple containing:
            1. The diagnostic output for the main file.
            2. A dictionary mapping header files to their diagnostics.
        """
        if not self.check_headers:
            return clang_tidy_output, {}

        header_messages = defaultdict(list)
        remaining_lines: List[str] = []
        current_file = ""

        for line in clang_tidy_output.splitlines(keepends=True):
            if re.match(r"^\d+ warnings? generated\.", line):
                continue

            # Matches the beginning of a clang-tidy diagnostic line,
            # which starts with "file_path:line:col: ".
            if match := re.match(r"^(.+):\d+:\d+: ", line):
                abs_path = os.path.normcase(os.path.abspath(match.group(1)))
                current_file = abs_path if abs_path in self.check_header_map else ""

            dest_list = (
                header_messages[current_file] if current_file else remaining_lines
            )
            dest_list.append(line)

        header_messages_str = {k: "".join(v) for k, v in header_messages.items()}
        return "".join(remaining_lines), header_messages_str

    def run(self) -> None:
        self.read_input()
        if self.export_fixes is None:
            self.get_prefixes()
        self.prepare_test_inputs()
        clang_tidy_output = self.run_clang_tidy()
        main_output, header_messages = self._separate_messages(clang_tidy_output)

        if self.expect_no_diagnosis:
            self.check_no_diagnosis(main_output)
        elif self.export_fixes is None:
            self.check_fixes()
            self.check_messages(main_output)
            self.check_notes(main_output)

            for temp_header, original_header in self.check_header_map.items():
                self.check_fixes(
                    input_file=temp_header,
                    check_file=original_header,
                )

                if temp_header in header_messages:
                    self.check_messages(
                        header_messages[temp_header],
                        messages_file=f"{temp_header}.msg",
                        check_file=original_header,
                    )


CPP_STANDARDS = [
    "c++98",
    "c++11",
    ("c++14", "c++1y"),
    ("c++17", "c++1z"),
    ("c++20", "c++2a"),
    ("c++23", "c++2b"),
    ("c++26", "c++2c"),
]
C_STANDARDS = ["c99", ("c11", "c1x"), "c17", ("c23", "c2x"), "c2y"]


def expand_std(std: str) -> List[str]:
    split_std, or_later, suffix = std.partition("-or-later")

    if or_later and suffix:
        # Keep malformed -or-later spellings unchanged so clang diagnoses them.
        return [std]

    if not or_later:
        return [split_std]

    for standard_list in (CPP_STANDARDS, C_STANDARDS):
        item = next(
            (
                i
                for i, v in enumerate(standard_list)
                if (split_std in v if isinstance(v, (list, tuple)) else split_std == v)
            ),
            None,
        )
        if item is not None:
            return [split_std] + [
                x if isinstance(x, str) else x[0] for x in standard_list[item + 1 :]
            ]
    return [std]


def csv(string: str) -> List[str]:
    return string.split(",")


def parse_arguments() -> Tuple[argparse.Namespace, List[str]]:
    parser = argparse.ArgumentParser(
        prog=pathlib.Path(__file__).stem,
        description=__doc__,
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument("-expect-clang-tidy-error", action="store_true")
    parser.add_argument("-resource-dir")
    parser.add_argument("-assume-filename")
    parser.add_argument("input_file_name")
    parser.add_argument("check_name")
    parser.add_argument("temp_file_name")
    parser.add_argument(
        "-check-suffix",
        "-check-suffixes",
        default=[""],
        type=csv,
        help="comma-separated list of FileCheck suffixes",
    )
    parser.add_argument(
        "-check-header",
        action="append",
        dest="check_headers",
        default=[],
        help="Header files to check",
    )
    parser.add_argument(
        "-export-fixes",
        default=None,
        type=str,
        metavar="file",
        help="A file to export fixes into instead of fixing.",
    )
    parser.add_argument(
        "-std",
        type=csv,
        default=None,
        help="Passed to clang. Special -or-later values are expanded.",
    )
    parser.add_argument(
        "--match-partial-fixes",
        action="store_true",
        help="allow partial line matches for fixes",
    )

    args, extra_args = parser.parse_known_args()
    if args.std is None:
        _, extension = os.path.splitext(args.assume_filename or args.input_file_name)
        args.std = ["c99-or-later" if extension in [".c", ".m"] else "c++11-or-later"]

    return (args, extra_args)


def main() -> None:
    sys.stdout.reconfigure(encoding="utf-8")
    sys.stderr.reconfigure(encoding="utf-8")
    args, extra_args = parse_arguments()

    abbreviated_stds = args.std
    for abbreviated_std in abbreviated_stds:
        for std in expand_std(abbreviated_std):
            args.std = std
            CheckRunner(args, extra_args).run()


if __name__ == "__main__":
    main()