feat: add --fix CLI option to auto-apply clang-format fixes - #202

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Locate FileObj construction and identify file-path validation before formatting.
ast-grep outline cpp_linter/common_fs.py --items all --match FileObj
rg -n -C 5 --glob '*.py' \
  'FileObj\(|is_symlink\(|resolve\(|relative_to\(|repo_root|lstat\(' \
  cpp_linter tests

# Trace the file list passed into the formatter worker.
rg -n -C 5 --glob '*.py' \
  'capture_clang_tools_output\(|_run_on_single_file\(' \
  cpp_linter tests

Repository: cpp-linter/cpp-linter

Length of output: 29770

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== common_fs files =="
git ls-files cpp_linter/common_fs

echo
echo "== locate FileObj definition =="
rg -n --glob '*.py' 'class FileObj|def __init__|def lstat|def is_symlink|def resolve|relative_to|repo_root|files_in_list|get_list' cpp_linter cpp_linter/common_fs tests || true

echo
echo "== FileObj definitions =="
for f in $(rg -l --glob '*.py' 'class FileObj' cpp_linter cpp_linter/common_fs tests || true); do
  echo "--- ${f#"$PWD/"}"
  sed -n '1,240p' "$f"
done

echo
echo "== file selection factories =="
sed -n '115,220p' cpp_linter/common_fs/file_filter.py
sed -n '110,150p' cpp_linter/__init__.py
sed -n '230,255p' cpp_linter/rest_api/github_api.py

echo
echo "== clang-format file argument handling =="
sed -n '160,235p' cpp_linter/clang_tools/clang_format.py

Repository: cpp-linter/cpp-linter

Length of output: 30977

🌐 Web query:

clang-format -i symlink behavior documentation follows symlink in-place

💡 Result:

The behavior of clang-format regarding symbolic links depends on the specific tool being used: 1. clang-format (the core command-line tool): When you run clang-format with the in-place editing flag (-i) on a file that is a symbolic link, it does not safely preserve the symlink. Instead, it effectively overwrites the symlink by replacing it with a regular file containing the formatted content [1]. It does not follow the symlink to format the target file while leaving the symlink itself intact; rather, it breaks the symlink connection [1]. 2. git-clang-format: This wrapper tool explicitly avoids this issue. Following a reported bug where it would break symlinks, git-clang-format was updated to detect and ignore symbolic links entirely, ensuring they are not formatted [2][3][1]. In summary, there is no built-in documentation or feature that makes clang-format "follow" a symlink to format the target in-place while respecting the symlink structure. If you need to format a target file pointed to by a symlink using the base clang-format tool, you must resolve the path to the actual target file manually before running the command [1].

Citations:

• 1: clang-format breaks symlinks llvm/llvm-project#46336
• 2: https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/git-clang-format
• 3: https://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20210510/369509.html

🌐 Web query:

site:clang.llvm.org/extra/clangd/clang_format.html or clang-format man page -i symbolic link behavior

💡 Result:

clang-format -i file edits the path you passed, but the official documentation does not specify special symbolic-link behavior—it only says -i performs an in-place edit. (clang.llvm.org)

On POSIX systems, this normally means:

• The symlink is followed when reading.
• The target file’s contents are updated.
• The symlink itself remains intact.

Example:

ln -s real.cpp alias.cpp
clang-format -i alias.cpp

real.cpp is formatted; alias.cpp remains a symlink. This follows standard pathname symlink semantics. (man7.org)

However, this is inferred behavior rather than a documented clang-format guarantee; test it if portability across platforms or versions matters.

Citations:

• 1: https://clang.llvm.org/docs/ClangFormat.html?utm_source=openai
• 2: https://man7.org/linux/man-pages/man7/symlink.7.html?utm_source=openai

🌐 Web query:

llvm-project clang-format tool.cpp argv[0] replace symlink in place rename operation -i

💡 Result:

The clang-format tool does not perform in-place rename operations on itself via symlink manipulation [1][2]. While the LLVM project uses symbolic links for managing versions of tools (e.g., creating unversioned clang-format links pointing to versioned binaries like clang-format-18) [3][4][5], these are installation-time or system-management artifacts, not runtime operations performed by the clang-format source code [1][2]. In the context of clang-format's behavior regarding symlinks and file processing: 1. File Handling: There have been reports of clang-format improperly handling symbolic links during in-place formatting (the -i flag), where it might replace a symlink with a regular file containing the formatted content [6]. This is generally considered an issue rather than an intended feature [6]. 2. argv Usage: In the broader LLVM Tooling library, argv is often used to locate the resource directory (e.g., standard library headers), but the project has moved toward injecting the resource directory explicitly rather than relying on or overwriting argv [7][8]. 3. Tooling Logic: The source code for clang-format (e.g., ClangFormat.cpp) and related tooling does not contain logic to rename or replace its own binary executable through symlink manipulation [1][2]. If you are seeing an issue where a symlink is being replaced, it is likely an artifact of how the operating system or file system handles the write operation during an in-place edit, rather than an explicit rename operation executed by the clang-format binary [6].

Citations:

• 1: https://llvm.googlesource.com/llvm-project/+/9a553d3766aacb69e884823da92dedff264e3f0f/clang/tools/clang-format
• 2: https://github.com/llvm/llvm-project/blob/main/clang/tools/clang-format/git-clang-format
• 3: https://cpp-linter.github.io/clang-tools-pip/
• 4: https://developer.lsst.io/cpp/clang-format.html
• 5: https://lists.llvm.org/pipermail/llvm-commits/Week-of-Mon-20161003/394387.html
• 6: clang-format breaks symlinks llvm/llvm-project#46336
• 7: https://github.com/llvm/llvm-project/blob/96196e25fd49e3d0ecec9550e81365ce122679cb/clang/lib/Tooling/Tooling.cpp
• 8: https://lists.llvm.org/pipermail/cfe-commits/Week-of-Mon-20160418/156225.html